From 11da511c784eca003deb90c23570f0873954e0de Mon Sep 17 00:00:00 2001 From: Duncan Wilkie Date: Sat, 18 Nov 2023 06:11:09 -0600 Subject: Initial commit. --- gmp-6.3.0/doc/Makefile | 847 +++ gmp-6.3.0/doc/Makefile.am | 36 + gmp-6.3.0/doc/Makefile.in | 847 +++ gmp-6.3.0/doc/configuration | 389 ++ gmp-6.3.0/doc/fdl-1.3.texi | 506 ++ gmp-6.3.0/doc/gmp.info | 179 + gmp-6.3.0/doc/gmp.info-1 | 7025 +++++++++++++++++++++++++ gmp-6.3.0/doc/gmp.info-2 | 4104 +++++++++++++++ gmp-6.3.0/doc/gmp.texi | 11073 +++++++++++++++++++++++++++++++++++++++ gmp-6.3.0/doc/isa_abi_headache | 128 + gmp-6.3.0/doc/mdate-sh | 224 + gmp-6.3.0/doc/projects.html | 476 ++ gmp-6.3.0/doc/stamp-vti | 4 + gmp-6.3.0/doc/tasks.html | 896 ++++ gmp-6.3.0/doc/texinfo.tex | 10079 +++++++++++++++++++++++++++++++++++ gmp-6.3.0/doc/version.texi | 4 + 16 files changed, 36817 insertions(+) create mode 100644 gmp-6.3.0/doc/Makefile create mode 100644 gmp-6.3.0/doc/Makefile.am create mode 100644 gmp-6.3.0/doc/Makefile.in create mode 100644 gmp-6.3.0/doc/configuration create mode 100644 gmp-6.3.0/doc/fdl-1.3.texi create mode 100644 gmp-6.3.0/doc/gmp.info create mode 100644 gmp-6.3.0/doc/gmp.info-1 create mode 100644 gmp-6.3.0/doc/gmp.info-2 create mode 100644 gmp-6.3.0/doc/gmp.texi create mode 100644 gmp-6.3.0/doc/isa_abi_headache create mode 100755 gmp-6.3.0/doc/mdate-sh create mode 100644 gmp-6.3.0/doc/projects.html create mode 100644 gmp-6.3.0/doc/stamp-vti create mode 100644 gmp-6.3.0/doc/tasks.html create mode 100644 gmp-6.3.0/doc/texinfo.tex create mode 100644 gmp-6.3.0/doc/version.texi (limited to 'gmp-6.3.0/doc') diff --git a/gmp-6.3.0/doc/Makefile b/gmp-6.3.0/doc/Makefile new file mode 100644 index 0000000..b5ada13 --- /dev/null +++ b/gmp-6.3.0/doc/Makefile @@ -0,0 +1,847 @@ +# Makefile.in generated by automake 1.15 from Makefile.am. +# doc/Makefile. Generated from Makefile.in by configure. + +# Copyright (C) 1994-2014 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + + + +# Copyright 2003 Free Software Foundation, Inc. +# +# This file is part of the GNU MP Library. +# +# The GNU MP Library is free software; you can redistribute it and/or modify +# it under the terms of either: +# +# * the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 3 of the License, or (at your +# option) any later version. +# +# or +# +# * the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any +# later version. +# +# or both in parallel, as here. +# +# The GNU MP Library is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received copies of the GNU General Public License and the +# GNU Lesser General Public License along with the GNU MP Library. If not, +# see https://www.gnu.org/licenses/. + +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/gmp +pkgincludedir = $(includedir)/gmp +pkglibdir = $(libdir)/gmp +pkglibexecdir = $(libexecdir)/gmp +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = pentiumm-pc-linux-gnu +host_triplet = pentiumm-pc-linux-gnu +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/version.texi \ + $(srcdir)/stamp-vti $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_$(V)) +am__v_P_ = $(am__v_P_$(AM_DEFAULT_VERBOSITY)) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +am__v_at_1 = +depcomp = +am__depfiles_maybe = +SOURCES = +DIST_SOURCES = +AM_V_DVIPS = $(am__v_DVIPS_$(V)) +am__v_DVIPS_ = $(am__v_DVIPS_$(AM_DEFAULT_VERBOSITY)) +am__v_DVIPS_0 = @echo " DVIPS " $@; +am__v_DVIPS_1 = +AM_V_MAKEINFO = $(am__v_MAKEINFO_$(V)) +am__v_MAKEINFO_ = $(am__v_MAKEINFO_$(AM_DEFAULT_VERBOSITY)) +am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 = +AM_V_INFOHTML = $(am__v_INFOHTML_$(V)) +am__v_INFOHTML_ = $(am__v_INFOHTML_$(AM_DEFAULT_VERBOSITY)) +am__v_INFOHTML_0 = @echo " INFOHTML" $@; +am__v_INFOHTML_1 = +AM_V_TEXI2DVI = $(am__v_TEXI2DVI_$(V)) +am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_$(AM_DEFAULT_VERBOSITY)) +am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 = +AM_V_TEXI2PDF = $(am__v_TEXI2PDF_$(V)) +am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_$(AM_DEFAULT_VERBOSITY)) +am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 = +AM_V_texinfo = $(am__v_texinfo_$(V)) +am__v_texinfo_ = $(am__v_texinfo_$(AM_DEFAULT_VERBOSITY)) +am__v_texinfo_0 = -q +am__v_texinfo_1 = +AM_V_texidevnull = $(am__v_texidevnull_$(V)) +am__v_texidevnull_ = $(am__v_texidevnull_$(AM_DEFAULT_VERBOSITY)) +am__v_texidevnull_0 = > /dev/null +am__v_texidevnull_1 = +INFO_DEPS = $(srcdir)/gmp.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = gmp.dvi +PDFS = gmp.pdf +PSS = gmp.ps +HTMLS = gmp.html +TEXINFOS = gmp.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(gmp_TEXINFOS) $(srcdir)/Makefile.in mdate-sh \ + texinfo.tex +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ABI = 32 +ACLOCAL = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/missing aclocal-1.15 +AMTAR = $${TAR-tar} +AM_DEFAULT_VERBOSITY = 1 +AR = ar +AS = as +ASMFLAGS = -Wa,--noexecstack +AUTOCONF = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/missing autoconf +AUTOHEADER = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/missing autoheader +AUTOMAKE = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/missing automake-1.15 +AWK = gawk +CALLING_CONVENTIONS_OBJS = x86call.lo x86check$U.lo +CC = gcc +CCAS = gcc -c +CC_FOR_BUILD = gcc +CFLAGS = -m32 -O2 -pedantic -fomit-frame-pointer -mtune=pentium3 -march=pentium3 +CPP = gcc -E +CPPFLAGS = +CPP_FOR_BUILD = gcc -E +CXX = +CXXCPP = +CXXFLAGS = +CYGPATH_W = echo +DEFN_LONG_LONG_LIMB = /* #undef _LONG_LONG_LIMB */ +DEFS = -DHAVE_CONFIG_H +DLLTOOL = dlltool +DSYMUTIL = +DUMPBIN = +ECHO_C = +ECHO_N = -n +ECHO_T = +EGREP = /usr/bin/grep -E +EXEEXT = +EXEEXT_FOR_BUILD = +FGREP = /usr/bin/grep -F +GMP_LDFLAGS = +GMP_LIMB_BITS = 32 +GMP_NAIL_BITS = 0 +GREP = /usr/bin/grep +HAVE_CLOCK_01 = 1 +HAVE_CPUTIME_01 = 0 +HAVE_GETRUSAGE_01 = 1 +HAVE_GETTIMEOFDAY_01 = 1 +HAVE_HOST_CPU_FAMILY_power = 0 +HAVE_HOST_CPU_FAMILY_powerpc = 0 +HAVE_SIGACTION_01 = 1 +HAVE_SIGALTSTACK_01 = 1 +HAVE_SIGSTACK_01 = 1 +HAVE_STACK_T_01 = 1 +HAVE_SYS_RESOURCE_H_01 = 1 +INSTALL = /usr/bin/install -c +INSTALL_DATA = ${INSTALL} -m 644 +INSTALL_PROGRAM = ${INSTALL} +INSTALL_SCRIPT = ${INSTALL} +INSTALL_STRIP_PROGRAM = $(install_sh) -c -s +LD = /usr/bin/ld +LDFLAGS = +LEX = flex +LEXLIB = -lfl +LEX_OUTPUT_ROOT = lex.yy +LIBCURSES = -lncurses +LIBGMPXX_LDFLAGS = +LIBGMP_DLL = 0 +LIBGMP_LDFLAGS = +LIBM = -lm +LIBM_FOR_BUILD = -lm +LIBOBJS = +LIBREADLINE = -lreadline +LIBS = +LIBTOOL = $(SHELL) $(top_builddir)/libtool +LIPO = +LN_S = ln -s +LTLIBOBJS = +LT_SYS_LIBRARY_PATH = +M4 = m4 +MAINT = # +MAKEINFO = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/missing makeinfo +MANIFEST_TOOL = : +MKDIR_P = /usr/bin/mkdir -p +NM = /usr/bin/nm -B +NMEDIT = +OBJDUMP = objdump +OBJEXT = o +OTOOL = +OTOOL64 = +PACKAGE = gmp +PACKAGE_BUGREPORT = gmp-bugs@gmplib.org (see https://gmplib.org/manual/Reporting-Bugs.html) +PACKAGE_NAME = GNU MP +PACKAGE_STRING = GNU MP 6.3.0 +PACKAGE_TARNAME = gmp +PACKAGE_URL = http://www.gnu.org/software/gmp/ +PACKAGE_VERSION = 6.3.0 +PATH_SEPARATOR = : +RANLIB = ranlib +SED = /usr/bin/sed +SET_MAKE = +SHELL = /bin/sh +SPEED_CYCLECOUNTER_OBJ = pentium.lo +STRIP = strip +TAL_OBJECT = tal-reent.lo +TUNE_LIBS = +TUNE_SQR_OBJ = +U_FOR_BUILD = +VERSION = 6.3.0 +WITH_READLINE_01 = 1 +YACC = bison -y +YFLAGS = +abs_builddir = /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/doc +abs_srcdir = /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/doc +abs_top_builddir = /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0 +abs_top_srcdir = /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0 +ac_ct_AR = ar +ac_ct_CC = gcc +ac_ct_CXX = +ac_ct_DUMPBIN = +am__leading_dot = . +am__tar = $${TAR-tar} chof - "$$tardir" +am__untar = $${TAR-tar} xf - +bindir = ${exec_prefix}/bin +build = pentiumm-pc-linux-gnu +build_alias = +build_cpu = pentiumm +build_os = linux-gnu +build_vendor = pc +builddir = . +datadir = ${datarootdir} +datarootdir = ${prefix}/share +docdir = ${datarootdir}/doc/${PACKAGE_TARNAME} +dvidir = ${docdir} +exec_prefix = ${prefix} +gmp_srclinks = mpn/add.c mpn/add_1.c mpn/add_n.asm mpn/sub.c mpn/sub_1.c mpn/sub_n.asm mpn/cnd_add_n.asm mpn/cnd_sub_n.asm mpn/cnd_swap.c mpn/neg.c mpn/com.c mpn/mul_1.asm mpn/addmul_1.asm mpn/submul_1.asm mpn/add_err1_n.c mpn/add_err2_n.c mpn/add_err3_n.c mpn/sub_err1_n.c mpn/sub_err2_n.c mpn/sub_err3_n.c mpn/lshift.asm mpn/rshift.asm mpn/dive_1.asm mpn/diveby3.c mpn/divis.c mpn/divrem.c mpn/divrem_1.asm mpn/divrem_2.asm mpn/fib2_ui.c mpn/fib2m.c mpn/mod_1.c mpn/mod_34lsub1.asm mpn/mode1o.asm mpn/pre_mod_1.c mpn/dump.c mpn/mod_1_1.asm mpn/mod_1_2.c mpn/mod_1_3.c mpn/mod_1_4.asm mpn/lshiftc.c mpn/mul.c mpn/mul_fft.c mpn/mul_n.c mpn/sqr.c mpn/mul_basecase.asm mpn/sqr_basecase.asm mpn/nussbaumer_mul.c mpn/mulmid_basecase.c mpn/toom42_mulmid.c mpn/mulmid_n.c mpn/mulmid.c mpn/random.c mpn/random2.c mpn/pow_1.c mpn/rootrem.c mpn/sqrtrem.c mpn/sizeinbase.c mpn/get_str.c mpn/set_str.c mpn/compute_powtab.c mpn/scan0.c mpn/scan1.c mpn/popcount.asm mpn/hamdist.asm mpn/cmp.c mpn/zero_p.c mpn/perfsqr.c mpn/perfpow.c mpn/strongfibo.c mpn/gcd_11.asm mpn/gcd_22.c mpn/gcd_1.c mpn/gcd.c mpn/gcdext_1.c mpn/gcdext.c mpn/gcd_subdiv_step.c mpn/gcdext_lehmer.c mpn/div_q.c mpn/tdiv_qr.c mpn/jacbase.c mpn/jacobi_2.c mpn/jacobi.c mpn/get_d.c mpn/matrix22_mul.c mpn/matrix22_mul1_inverse_vector.c mpn/hgcd_matrix.c mpn/hgcd2.c mpn/hgcd_step.c mpn/hgcd_reduce.c mpn/hgcd.c mpn/hgcd_appr.c mpn/hgcd2_jacobi.c mpn/hgcd_jacobi.c mpn/mullo_n.c mpn/mullo_basecase.c mpn/sqrlo.c mpn/sqrlo_basecase.c mpn/toom22_mul.c mpn/toom32_mul.c mpn/toom42_mul.c mpn/toom52_mul.c mpn/toom62_mul.c mpn/toom33_mul.c mpn/toom43_mul.c mpn/toom53_mul.c mpn/toom54_mul.c mpn/toom63_mul.c mpn/toom44_mul.c mpn/toom6h_mul.c mpn/toom6_sqr.c mpn/toom8h_mul.c mpn/toom8_sqr.c mpn/toom_couple_handling.c mpn/toom2_sqr.c mpn/toom3_sqr.c mpn/toom4_sqr.c mpn/toom_eval_dgr3_pm1.c mpn/toom_eval_dgr3_pm2.c mpn/toom_eval_pm1.c mpn/toom_eval_pm2.c mpn/toom_eval_pm2exp.c mpn/toom_eval_pm2rexp.c mpn/toom_interpolate_5pts.c mpn/toom_interpolate_6pts.c mpn/toom_interpolate_7pts.c mpn/toom_interpolate_8pts.c mpn/toom_interpolate_12pts.c mpn/toom_interpolate_16pts.c mpn/invertappr.c mpn/invert.c mpn/binvert.c mpn/mulmod_bnm1.c mpn/sqrmod_bnm1.c mpn/mulmod_bknp1.c mpn/div_qr_1.c mpn/div_qr_1n_pi1.c mpn/div_qr_2.c mpn/div_qr_2n_pi1.c mpn/div_qr_2u_pi1.c mpn/sbpi1_div_q.c mpn/sbpi1_div_qr.c mpn/sbpi1_divappr_q.c mpn/dcpi1_div_q.c mpn/dcpi1_div_qr.c mpn/dcpi1_divappr_q.c mpn/mu_div_qr.c mpn/mu_divappr_q.c mpn/mu_div_q.c mpn/bdiv_q_1.asm mpn/sbpi1_bdiv_q.c mpn/sbpi1_bdiv_qr.c mpn/sbpi1_bdiv_r.c mpn/dcpi1_bdiv_q.c mpn/dcpi1_bdiv_qr.c mpn/mu_bdiv_q.c mpn/mu_bdiv_qr.c mpn/bdiv_q.c mpn/bdiv_qr.c mpn/broot.c mpn/brootinv.c mpn/bsqrt.c mpn/bsqrtinv.c mpn/divexact.c mpn/bdiv_dbm1c.asm mpn/redc_1.c mpn/redc_2.c mpn/redc_n.c mpn/powm.c mpn/powlo.c mpn/sec_powm.c mpn/sec_mul.c mpn/sec_sqr.c mpn/sec_div_qr.c mpn/sec_div_r.c mpn/sec_pi1_div_qr.c mpn/sec_pi1_div_r.c mpn/sec_add_1.c mpn/sec_sub_1.c mpn/sec_invert.c mpn/trialdiv.c mpn/remove.c mpn/and_n.c mpn/andn_n.c mpn/nand_n.c mpn/ior_n.c mpn/iorn_n.c mpn/nior_n.c mpn/xor_n.c mpn/xnor_n.c mpn/copyi.asm mpn/copyd.asm mpn/zero.c mpn/sec_tabselect.asm mpn/comb_tables.c mpn/umul.asm mpn/udiv.asm mpn/add_n_sub_n.c gmp-mparam.h +host = pentiumm-pc-linux-gnu +host_alias = +host_cpu = pentiumm +host_os = linux-gnu +host_vendor = pc +htmldir = ${docdir} +includedir = ${prefix}/include +infodir = ${datarootdir}/info +install_sh = ${SHELL} /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/install-sh +libdir = ${exec_prefix}/lib +libexecdir = ${exec_prefix}/libexec +localedir = ${datarootdir}/locale +localstatedir = ${prefix}/var +mandir = ${datarootdir}/man +mkdir_p = $(MKDIR_P) +mpn_objects = add$U.lo add_1$U.lo add_n.lo sub$U.lo sub_1$U.lo sub_n.lo cnd_add_n.lo cnd_sub_n.lo cnd_swap$U.lo neg$U.lo com$U.lo mul_1.lo addmul_1.lo submul_1.lo add_err1_n$U.lo add_err2_n$U.lo add_err3_n$U.lo sub_err1_n$U.lo sub_err2_n$U.lo sub_err3_n$U.lo lshift.lo rshift.lo dive_1.lo diveby3$U.lo divis$U.lo divrem$U.lo divrem_1.lo divrem_2.lo fib2_ui$U.lo fib2m$U.lo mod_1$U.lo mod_34lsub1.lo mode1o.lo pre_mod_1$U.lo dump$U.lo mod_1_1.lo mod_1_2$U.lo mod_1_3$U.lo mod_1_4.lo lshiftc$U.lo mul$U.lo mul_fft$U.lo mul_n$U.lo sqr$U.lo mul_basecase.lo sqr_basecase.lo nussbaumer_mul$U.lo mulmid_basecase$U.lo toom42_mulmid$U.lo mulmid_n$U.lo mulmid$U.lo random$U.lo random2$U.lo pow_1$U.lo rootrem$U.lo sqrtrem$U.lo sizeinbase$U.lo get_str$U.lo set_str$U.lo compute_powtab$U.lo scan0$U.lo scan1$U.lo popcount.lo hamdist.lo cmp$U.lo zero_p$U.lo perfsqr$U.lo perfpow$U.lo strongfibo$U.lo gcd_11.lo gcd_22$U.lo gcd_1$U.lo gcd$U.lo gcdext_1$U.lo gcdext$U.lo gcd_subdiv_step$U.lo gcdext_lehmer$U.lo div_q$U.lo tdiv_qr$U.lo jacbase$U.lo jacobi_2$U.lo jacobi$U.lo get_d$U.lo matrix22_mul$U.lo matrix22_mul1_inverse_vector$U.lo hgcd_matrix$U.lo hgcd2$U.lo hgcd_step$U.lo hgcd_reduce$U.lo hgcd$U.lo hgcd_appr$U.lo hgcd2_jacobi$U.lo hgcd_jacobi$U.lo mullo_n$U.lo mullo_basecase$U.lo sqrlo$U.lo sqrlo_basecase$U.lo toom22_mul$U.lo toom32_mul$U.lo toom42_mul$U.lo toom52_mul$U.lo toom62_mul$U.lo toom33_mul$U.lo toom43_mul$U.lo toom53_mul$U.lo toom54_mul$U.lo toom63_mul$U.lo toom44_mul$U.lo toom6h_mul$U.lo toom6_sqr$U.lo toom8h_mul$U.lo toom8_sqr$U.lo toom_couple_handling$U.lo toom2_sqr$U.lo toom3_sqr$U.lo toom4_sqr$U.lo toom_eval_dgr3_pm1$U.lo toom_eval_dgr3_pm2$U.lo toom_eval_pm1$U.lo toom_eval_pm2$U.lo toom_eval_pm2exp$U.lo toom_eval_pm2rexp$U.lo toom_interpolate_5pts$U.lo toom_interpolate_6pts$U.lo toom_interpolate_7pts$U.lo toom_interpolate_8pts$U.lo toom_interpolate_12pts$U.lo toom_interpolate_16pts$U.lo invertappr$U.lo invert$U.lo binvert$U.lo mulmod_bnm1$U.lo sqrmod_bnm1$U.lo mulmod_bknp1$U.lo div_qr_1$U.lo div_qr_1n_pi1$U.lo div_qr_2$U.lo div_qr_2n_pi1$U.lo div_qr_2u_pi1$U.lo sbpi1_div_q$U.lo sbpi1_div_qr$U.lo sbpi1_divappr_q$U.lo dcpi1_div_q$U.lo dcpi1_div_qr$U.lo dcpi1_divappr_q$U.lo mu_div_qr$U.lo mu_divappr_q$U.lo mu_div_q$U.lo bdiv_q_1.lo sbpi1_bdiv_q$U.lo sbpi1_bdiv_qr$U.lo sbpi1_bdiv_r$U.lo dcpi1_bdiv_q$U.lo dcpi1_bdiv_qr$U.lo mu_bdiv_q$U.lo mu_bdiv_qr$U.lo bdiv_q$U.lo bdiv_qr$U.lo broot$U.lo brootinv$U.lo bsqrt$U.lo bsqrtinv$U.lo divexact$U.lo bdiv_dbm1c.lo redc_1$U.lo redc_2$U.lo redc_n$U.lo powm$U.lo powlo$U.lo sec_powm$U.lo sec_mul$U.lo sec_sqr$U.lo sec_div_qr$U.lo sec_div_r$U.lo sec_pi1_div_qr$U.lo sec_pi1_div_r$U.lo sec_add_1$U.lo sec_sub_1$U.lo sec_invert$U.lo trialdiv$U.lo remove$U.lo and_n$U.lo andn_n$U.lo nand_n$U.lo ior_n$U.lo iorn_n$U.lo nior_n$U.lo xor_n$U.lo xnor_n$U.lo copyi.lo copyd.lo zero$U.lo sec_tabselect.lo comb_tables$U.lo umul.lo udiv.lo add_n_sub_n$U.lo +mpn_objs_in_libgmp = mpn/add$U.lo mpn/add_1$U.lo mpn/add_n.lo mpn/sub$U.lo mpn/sub_1$U.lo mpn/sub_n.lo mpn/cnd_add_n.lo mpn/cnd_sub_n.lo mpn/cnd_swap$U.lo mpn/neg$U.lo mpn/com$U.lo mpn/mul_1.lo mpn/addmul_1.lo mpn/submul_1.lo mpn/add_err1_n$U.lo mpn/add_err2_n$U.lo mpn/add_err3_n$U.lo mpn/sub_err1_n$U.lo mpn/sub_err2_n$U.lo mpn/sub_err3_n$U.lo mpn/lshift.lo mpn/rshift.lo mpn/dive_1.lo mpn/diveby3$U.lo mpn/divis$U.lo mpn/divrem$U.lo mpn/divrem_1.lo mpn/divrem_2.lo mpn/fib2_ui$U.lo mpn/fib2m$U.lo mpn/mod_1$U.lo mpn/mod_34lsub1.lo mpn/mode1o.lo mpn/pre_mod_1$U.lo mpn/dump$U.lo mpn/mod_1_1.lo mpn/mod_1_2$U.lo mpn/mod_1_3$U.lo mpn/mod_1_4.lo mpn/lshiftc$U.lo mpn/mul$U.lo mpn/mul_fft$U.lo mpn/mul_n$U.lo mpn/sqr$U.lo mpn/mul_basecase.lo mpn/sqr_basecase.lo mpn/nussbaumer_mul$U.lo mpn/mulmid_basecase$U.lo mpn/toom42_mulmid$U.lo mpn/mulmid_n$U.lo mpn/mulmid$U.lo mpn/random$U.lo mpn/random2$U.lo mpn/pow_1$U.lo mpn/rootrem$U.lo mpn/sqrtrem$U.lo mpn/sizeinbase$U.lo mpn/get_str$U.lo mpn/set_str$U.lo mpn/compute_powtab$U.lo mpn/scan0$U.lo mpn/scan1$U.lo mpn/popcount.lo mpn/hamdist.lo mpn/cmp$U.lo mpn/zero_p$U.lo mpn/perfsqr$U.lo mpn/perfpow$U.lo mpn/strongfibo$U.lo mpn/gcd_11.lo mpn/gcd_22$U.lo mpn/gcd_1$U.lo mpn/gcd$U.lo mpn/gcdext_1$U.lo mpn/gcdext$U.lo mpn/gcd_subdiv_step$U.lo mpn/gcdext_lehmer$U.lo mpn/div_q$U.lo mpn/tdiv_qr$U.lo mpn/jacbase$U.lo mpn/jacobi_2$U.lo mpn/jacobi$U.lo mpn/get_d$U.lo mpn/matrix22_mul$U.lo mpn/matrix22_mul1_inverse_vector$U.lo mpn/hgcd_matrix$U.lo mpn/hgcd2$U.lo mpn/hgcd_step$U.lo mpn/hgcd_reduce$U.lo mpn/hgcd$U.lo mpn/hgcd_appr$U.lo mpn/hgcd2_jacobi$U.lo mpn/hgcd_jacobi$U.lo mpn/mullo_n$U.lo mpn/mullo_basecase$U.lo mpn/sqrlo$U.lo mpn/sqrlo_basecase$U.lo mpn/toom22_mul$U.lo mpn/toom32_mul$U.lo mpn/toom42_mul$U.lo mpn/toom52_mul$U.lo mpn/toom62_mul$U.lo mpn/toom33_mul$U.lo mpn/toom43_mul$U.lo mpn/toom53_mul$U.lo mpn/toom54_mul$U.lo mpn/toom63_mul$U.lo mpn/toom44_mul$U.lo mpn/toom6h_mul$U.lo mpn/toom6_sqr$U.lo mpn/toom8h_mul$U.lo mpn/toom8_sqr$U.lo mpn/toom_couple_handling$U.lo mpn/toom2_sqr$U.lo mpn/toom3_sqr$U.lo mpn/toom4_sqr$U.lo mpn/toom_eval_dgr3_pm1$U.lo mpn/toom_eval_dgr3_pm2$U.lo mpn/toom_eval_pm1$U.lo mpn/toom_eval_pm2$U.lo mpn/toom_eval_pm2exp$U.lo mpn/toom_eval_pm2rexp$U.lo mpn/toom_interpolate_5pts$U.lo mpn/toom_interpolate_6pts$U.lo mpn/toom_interpolate_7pts$U.lo mpn/toom_interpolate_8pts$U.lo mpn/toom_interpolate_12pts$U.lo mpn/toom_interpolate_16pts$U.lo mpn/invertappr$U.lo mpn/invert$U.lo mpn/binvert$U.lo mpn/mulmod_bnm1$U.lo mpn/sqrmod_bnm1$U.lo mpn/mulmod_bknp1$U.lo mpn/div_qr_1$U.lo mpn/div_qr_1n_pi1$U.lo mpn/div_qr_2$U.lo mpn/div_qr_2n_pi1$U.lo mpn/div_qr_2u_pi1$U.lo mpn/sbpi1_div_q$U.lo mpn/sbpi1_div_qr$U.lo mpn/sbpi1_divappr_q$U.lo mpn/dcpi1_div_q$U.lo mpn/dcpi1_div_qr$U.lo mpn/dcpi1_divappr_q$U.lo mpn/mu_div_qr$U.lo mpn/mu_divappr_q$U.lo mpn/mu_div_q$U.lo mpn/bdiv_q_1.lo mpn/sbpi1_bdiv_q$U.lo mpn/sbpi1_bdiv_qr$U.lo mpn/sbpi1_bdiv_r$U.lo mpn/dcpi1_bdiv_q$U.lo mpn/dcpi1_bdiv_qr$U.lo mpn/mu_bdiv_q$U.lo mpn/mu_bdiv_qr$U.lo mpn/bdiv_q$U.lo mpn/bdiv_qr$U.lo mpn/broot$U.lo mpn/brootinv$U.lo mpn/bsqrt$U.lo mpn/bsqrtinv$U.lo mpn/divexact$U.lo mpn/bdiv_dbm1c.lo mpn/redc_1$U.lo mpn/redc_2$U.lo mpn/redc_n$U.lo mpn/powm$U.lo mpn/powlo$U.lo mpn/sec_powm$U.lo mpn/sec_mul$U.lo mpn/sec_sqr$U.lo mpn/sec_div_qr$U.lo mpn/sec_div_r$U.lo mpn/sec_pi1_div_qr$U.lo mpn/sec_pi1_div_r$U.lo mpn/sec_add_1$U.lo mpn/sec_sub_1$U.lo mpn/sec_invert$U.lo mpn/trialdiv$U.lo mpn/remove$U.lo mpn/and_n$U.lo mpn/andn_n$U.lo mpn/nand_n$U.lo mpn/ior_n$U.lo mpn/iorn_n$U.lo mpn/nior_n$U.lo mpn/xor_n$U.lo mpn/xnor_n$U.lo mpn/copyi.lo mpn/copyd.lo mpn/zero$U.lo mpn/sec_tabselect.lo mpn/comb_tables$U.lo mpn/umul.lo mpn/udiv.lo mpn/add_n_sub_n$U.lo +oldincludedir = /usr/include +pdfdir = ${docdir} +prefix = /home/dnw/Code/ERA-calc/c-src/gmp-6.3.0/bin +program_transform_name = s,x,x, +psdir = ${docdir} +sbindir = ${exec_prefix}/sbin +sharedstatedir = ${prefix}/com +srcdir = . +sysconfdir = ${prefix}/etc +target_alias = +top_build_prefix = ../ +top_builddir = .. +top_srcdir = .. +EXTRA_DIST = configuration isa_abi_headache projects.html tasks.html +info_TEXINFOS = gmp.texi +gmp_TEXINFOS = fdl-1.3.texi +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: # $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu --ignore-deps doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu --ignore-deps doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: # $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): # $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.pdf: + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.html: + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/gmp.info: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.dvi: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.pdf: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.html: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +$(srcdir)/version.texi: # $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: gmp.texi $(top_srcdir)/configure + @(dir=.; test -f ./gmp.texi || dir=$(srcdir); \ + set `$(SHELL) $(srcdir)/mdate-sh $$dir/gmp.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp$$$$ && \ + (cmp -s vti.tmp$$$$ $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi" && \ + cp vti.tmp$$$$ $(srcdir)/version.texi.tmp$$$$ && \ + mv $(srcdir)/version.texi.tmp$$$$ $(srcdir)/version.texi)) && \ + rm -f vti.tmp$$$$ $(srcdir)/version.texi.$$$$ + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp* $(srcdir)/version.texi.tmp* + +maintainer-clean-vti: +# -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf gmp.t2d gmp.t2p + +clean-aminfo: + -test -z "gmp.dvi gmp.pdf gmp.ps gmp.html" \ + || rm -rf gmp.dvi gmp.pdf gmp.ps gmp.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + d2=$$d$$p; \ + if test -d "$$d2"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d2"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ + fi; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool cscopelist-am ctags-am dist-info distclean \ + distclean-generic distclean-libtool distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-aminfo \ + mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \ + pdf-am ps ps-am tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.PRECIOUS: Makefile + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/gmp-6.3.0/doc/Makefile.am b/gmp-6.3.0/doc/Makefile.am new file mode 100644 index 0000000..083f25a --- /dev/null +++ b/gmp-6.3.0/doc/Makefile.am @@ -0,0 +1,36 @@ +## Process this file with automake to generate Makefile.in + + +# Copyright 2003 Free Software Foundation, Inc. +# +# This file is part of the GNU MP Library. +# +# The GNU MP Library is free software; you can redistribute it and/or modify +# it under the terms of either: +# +# * the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 3 of the License, or (at your +# option) any later version. +# +# or +# +# * the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any +# later version. +# +# or both in parallel, as here. +# +# The GNU MP Library is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received copies of the GNU General Public License and the +# GNU Lesser General Public License along with the GNU MP Library. If not, +# see https://www.gnu.org/licenses/. + + +EXTRA_DIST = configuration isa_abi_headache projects.html tasks.html + +info_TEXINFOS = gmp.texi +gmp_TEXINFOS = fdl-1.3.texi diff --git a/gmp-6.3.0/doc/Makefile.in b/gmp-6.3.0/doc/Makefile.in new file mode 100644 index 0000000..2d342b8 --- /dev/null +++ b/gmp-6.3.0/doc/Makefile.in @@ -0,0 +1,847 @@ +# Makefile.in generated by automake 1.15 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2014 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Copyright 2003 Free Software Foundation, Inc. +# +# This file is part of the GNU MP Library. +# +# The GNU MP Library is free software; you can redistribute it and/or modify +# it under the terms of either: +# +# * the GNU Lesser General Public License as published by the Free +# Software Foundation; either version 3 of the License, or (at your +# option) any later version. +# +# or +# +# * the GNU General Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at your option) any +# later version. +# +# or both in parallel, as here. +# +# The GNU MP Library is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received copies of the GNU General Public License and the +# GNU Lesser General Public License along with the GNU MP Library. If not, +# see https://www.gnu.org/licenses/. +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/version.texi \ + $(srcdir)/stamp-vti $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +depcomp = +am__depfiles_maybe = +SOURCES = +DIST_SOURCES = +AM_V_DVIPS = $(am__v_DVIPS_@AM_V@) +am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@) +am__v_DVIPS_0 = @echo " DVIPS " $@; +am__v_DVIPS_1 = +AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@) +am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@) +am__v_MAKEINFO_0 = @echo " MAKEINFO" $@; +am__v_MAKEINFO_1 = +AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@) +am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@) +am__v_INFOHTML_0 = @echo " INFOHTML" $@; +am__v_INFOHTML_1 = +AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@) +am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@) +am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@; +am__v_TEXI2DVI_1 = +AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@) +am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@) +am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@; +am__v_TEXI2PDF_1 = +AM_V_texinfo = $(am__v_texinfo_@AM_V@) +am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@) +am__v_texinfo_0 = -q +am__v_texinfo_1 = +AM_V_texidevnull = $(am__v_texidevnull_@AM_V@) +am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@) +am__v_texidevnull_0 = > /dev/null +am__v_texidevnull_1 = +INFO_DEPS = $(srcdir)/gmp.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = gmp.dvi +PDFS = gmp.pdf +PSS = gmp.ps +HTMLS = gmp.html +TEXINFOS = gmp.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(gmp_TEXINFOS) $(srcdir)/Makefile.in mdate-sh \ + texinfo.tex +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ABI = @ABI@ +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AS = @AS@ +ASMFLAGS = @ASMFLAGS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CALLING_CONVENTIONS_OBJS = @CALLING_CONVENTIONS_OBJS@ +CC = @CC@ +CCAS = @CCAS@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CPP_FOR_BUILD = @CPP_FOR_BUILD@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFN_LONG_LONG_LIMB = @DEFN_LONG_LONG_LIMB@ +DEFS = @DEFS@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +EXEEXT_FOR_BUILD = @EXEEXT_FOR_BUILD@ +FGREP = @FGREP@ +GMP_LDFLAGS = @GMP_LDFLAGS@ +GMP_LIMB_BITS = @GMP_LIMB_BITS@ +GMP_NAIL_BITS = @GMP_NAIL_BITS@ +GREP = @GREP@ +HAVE_CLOCK_01 = @HAVE_CLOCK_01@ +HAVE_CPUTIME_01 = @HAVE_CPUTIME_01@ +HAVE_GETRUSAGE_01 = @HAVE_GETRUSAGE_01@ +HAVE_GETTIMEOFDAY_01 = @HAVE_GETTIMEOFDAY_01@ +HAVE_HOST_CPU_FAMILY_power = @HAVE_HOST_CPU_FAMILY_power@ +HAVE_HOST_CPU_FAMILY_powerpc = @HAVE_HOST_CPU_FAMILY_powerpc@ +HAVE_SIGACTION_01 = @HAVE_SIGACTION_01@ +HAVE_SIGALTSTACK_01 = @HAVE_SIGALTSTACK_01@ +HAVE_SIGSTACK_01 = @HAVE_SIGSTACK_01@ +HAVE_STACK_T_01 = @HAVE_STACK_T_01@ +HAVE_SYS_RESOURCE_H_01 = @HAVE_SYS_RESOURCE_H_01@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LEX = @LEX@ +LEXLIB = @LEXLIB@ +LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ +LIBCURSES = @LIBCURSES@ +LIBGMPXX_LDFLAGS = @LIBGMPXX_LDFLAGS@ +LIBGMP_DLL = @LIBGMP_DLL@ +LIBGMP_LDFLAGS = @LIBGMP_LDFLAGS@ +LIBM = @LIBM@ +LIBM_FOR_BUILD = @LIBM_FOR_BUILD@ +LIBOBJS = @LIBOBJS@ +LIBREADLINE = @LIBREADLINE@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +M4 = @M4@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SPEED_CYCLECOUNTER_OBJ = @SPEED_CYCLECOUNTER_OBJ@ +STRIP = @STRIP@ +TAL_OBJECT = @TAL_OBJECT@ +TUNE_LIBS = @TUNE_LIBS@ +TUNE_SQR_OBJ = @TUNE_SQR_OBJ@ +U_FOR_BUILD = @U_FOR_BUILD@ +VERSION = @VERSION@ +WITH_READLINE_01 = @WITH_READLINE_01@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__leading_dot = @am__leading_dot@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +gmp_srclinks = @gmp_srclinks@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +mpn_objects = @mpn_objects@ +mpn_objs_in_libgmp = @mpn_objs_in_libgmp@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +EXTRA_DIST = configuration isa_abi_headache projects.html tasks.html +info_TEXINFOS = gmp.texi +gmp_TEXINFOS = fdl-1.3.texi +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu --ignore-deps doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu --ignore-deps doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + $(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + $(am__cd) $(srcdir); \ + else \ + rc=$$?; \ + $(am__cd) $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + $(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.pdf: + $(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \ + $< + +.texi.html: + $(AM_V_MAKEINFO)rm -rf $(@:.html=.htp) + $(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@ && mv $(@:.html=.htp) $@; \ + else \ + rm -rf $(@:.html=.htp); exit 1; \ + fi +$(srcdir)/gmp.info: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.dvi: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.pdf: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +gmp.html: gmp.texi $(srcdir)/version.texi $(gmp_TEXINFOS) +$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: gmp.texi $(top_srcdir)/configure + @(dir=.; test -f ./gmp.texi || dir=$(srcdir); \ + set `$(SHELL) $(srcdir)/mdate-sh $$dir/gmp.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp$$$$ && \ + (cmp -s vti.tmp$$$$ $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi" && \ + cp vti.tmp$$$$ $(srcdir)/version.texi.tmp$$$$ && \ + mv $(srcdir)/version.texi.tmp$$$$ $(srcdir)/version.texi)) && \ + rm -f vti.tmp$$$$ $(srcdir)/version.texi.$$$$ + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp* $(srcdir)/version.texi.tmp* + +maintainer-clean-vti: +@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + $(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) $(AM_V_texinfo) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf gmp.t2d gmp.t2p + +clean-aminfo: + -test -z "gmp.dvi gmp.pdf gmp.ps gmp.html" \ + || rm -rf gmp.dvi gmp.pdf gmp.ps gmp.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + $(am__strip_dir) \ + d2=$$d$$p; \ + if test -d "$$d2"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ + else \ + list2="$$list2 $$d2"; \ + fi; \ + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \ + fi; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + echo "$$ifile"; \ + else : ; fi; \ + done; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done + @$(POST_INSTALL) + @if $(am__can_run_installinfo); then \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + if test -n "$$list"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \ + fi; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool cscopelist-am ctags-am dist-info distclean \ + distclean-generic distclean-libtool distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-dvi install-dvi-am install-exec \ + install-exec-am install-html install-html-am install-info \ + install-info-am install-man install-pdf install-pdf-am \ + install-ps install-ps-am install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-aminfo maintainer-clean-generic \ + maintainer-clean-vti mostlyclean mostlyclean-aminfo \ + mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \ + pdf-am ps ps-am tags-am uninstall uninstall-am \ + uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.PRECIOUS: Makefile + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/gmp-6.3.0/doc/configuration b/gmp-6.3.0/doc/configuration new file mode 100644 index 0000000..f3a541b --- /dev/null +++ b/gmp-6.3.0/doc/configuration @@ -0,0 +1,389 @@ +/* doc/configuration (in Emacs -*-outline-*- format). */ + +Copyright 2000-2004 Free Software Foundation, Inc. + +This file is part of the GNU MP Library. + +The GNU MP Library is free software; you can redistribute it and/or modify +it under the terms of either: + + * the GNU Lesser General Public License as published by the Free + Software Foundation; either version 3 of the License, or (at your + option) any later version. + +or + + * the GNU General Public License as published by the Free Software + Foundation; either version 2 of the License, or (at your option) any + later version. + +or both in parallel, as here. + +The GNU MP Library is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for more details. + +You should have received copies of the GNU General Public License and the +GNU Lesser General Public License along with the GNU MP Library. If not, +see https://www.gnu.org/licenses/. + + + +* Adding a new file + +** Adding a top-level file + + i) Add it to libgmp_la_SOURCES in Makefile.am. + + ii) If libmp.la needs it (usually doesn't), then add it to + libmp_la_SOURCES too. + +** Adding a subdirectory file + +For instance for mpz, + + i) Add file.c to libmpz_la_SOURCES in mpz/Makefile.am. + + ii) Add mpz/file$U.lo to MPZ_OBJECTS in the top-level Makefile.am + + iii) If for some reason libmp.la needs it (usually doesn't) then add + mpz/file$U.lo to libmp_la_DEPENDENCIES in the top-level + Makefile.am too. + +The same applies to mpf, mpq, scanf and printf. + +** Adding an mpn file + +The way we build libmpn (in the `mpn' subdirectory) is quite special. + +Currently only mpn/mp_bases.c is truly generic and included in every +configuration. All other files are linked at build time into the mpn +build directory from one of the CPU specific sub-directories, or from +the mpn/generic directory. + +There are four types of mpn source files. + + .asm Assembly code preprocessed with m4 + .S Assembly code preprocessed with cpp + .s Assembly code not preprocessed at all + .c C code + +There are two types of .asm files. + + i) ``Normal'' files containing one function, though possibly with + more than one entry point. + + ii) Multi-function files that generate one of a set of functions + according to build options. + +To add a new implementation of an existing function, + + i) Put it in the appropriate CPU-specific mpn subdirectory, it'll be + detected and used. + + ii) Any entrypoints tested by HAVE_NATIVE_func in other code must + have PROLOGUE(func) for configure to grep. This is normal for + .asm or .S files, but for .c files a dummy comment like the + following will be needed. + + /* + PROLOGUE(func) + */ + +To add a new implementation using a multi-function file, in addition +do the following, + + i) Use a MULFUNC_PROLOGUE(func1 func2 ...) in the .asm, declaring + all the functions implemented, including carry-in variants. + + If there's a separate PROLOGUE(func) for each possible function + (but this is usually not the case), then MULFUNC_PROLOGUE isn't + necessary. + +To add a new style of multi-function file, in addition do the +following, + + i) Add to the GMP_MULFUNC_CHOICES "case" statement in configure.in + which lists each multi-function filename and what function files + it can provide. + +To add a completely new mpn function file, do the following, + + i) Ensure the filename is a valid C identifier, due to the + -DOPERATION_$* used to support multi-function files. This means + "-" can't be used (but "_" can). + + ii) Add it to configure.in under one of the following + + a) `gmp_mpn_functions' if it exists for every target. This + means there must be a C version in mpn/generic. (Eg. mul_1) + + b) `gmp_mpn_functions_optional' if it's a standard function, but + doesn't need to exist for every target. Code wanting to use + this will test HAVE_NATIVE_func to see if it's available. + (Eg. copyi) + + c) `extra_functions' for some targets, if it's a special + function that only ever needs to exist for certain targets. + Code wanting to use it can test either HAVE_NATIVE_func or + HAVE_HOST_CPU_foo, as desired. + + iii) If HAVE_NATIVE_func is going to be used, then add a #undef to + the AH_VERBATIM([HAVE_NATIVE] block in configure.in. + + iv) If the function can be provided by a multi-function file, then + add to the "case" statement in configure.in which lists each + multi-function filename and what function files it can provide. + + +** Adding a test program + + i) Tests to be run early in the testing can be added to the main + "tests" sub-directory. + + ii) Tests for mpn, mpz, mpq and mpf can be added under the + corresponding tests subdirectory. + + iii) Generic tests for late in the testing can be added to + "tests/misc". printf and scanf tests currently live there too. + + iv) Random number function tests can be added to "tests/rand". That + directory has some development-time programs too. + + v) C++ test programs can be added to "tests/cxx". A line like the + following must be added for each, since by default automake looks + for a .c file. + + t_foo_SOURCES = t-foo.cc + +In all cases the name of the program should be added to check_PROGRAMS +in the Makefile.am. TESTS is equal to check_PROGRAMS, so all those +programs get run. + +"tests/devel" has a number of programs which are only for development +purposes and are not for use in "make check". These should be listed +in EXTRA_PROGRAMS to get Makefile rules created, but they're never +built or run unless an explicit "make someprog" is used. + + +* Adding a new CPU + +In general it's policy to use proper names for each CPU type +supported. If two CPUs are quite similar and perhaps don't have any +actual differences in GMP then they're still given separate names, for +example alphaev67 and alphaev68. + +Canonical names: + + i) Decide the canonical CPU names GMP will accept. + + ii) Add these to the config.sub wrapper if configfsf.sub doesn't + already accept them. + + iii) Document the names in gmp.texi. + +Aliases (optional): + + i) Any aliases can be added to the config.sub wrapper, unless + configfsf.sub already does the right thing with them. + + ii) Leave configure.in and everywhere else using only the canonical + names. Aliases shouldn't appear anywhere except config.sub. + + iii) Document in gmp.texi, if desired. Usually this isn't a good + idea, better encourage users to know just the canonical + names. + +Configure: + + i) Add patterns to configure.in for the new CPU names. Include the + following (see configure.in for the variables to set up), + + a) ABI choices (if any). + b) Compiler choices. + c) mpn path for CPU specific code. + d) Good default CFLAGS for each likely compiler. + d) Any special tests necessary on the compiler or assembler + capabilities. + + ii) M4 macros to be shared by asm files in a CPU family are by + convention in a foo-defs.m4 like mpn/x86/x86-defs.m4. They're + likely to use settings from config.m4 generated by configure. + +Fat binaries: + + i) In configure.in, add CPU specific directory(s) to fat_path. + + ii) In mpn//fat.c, identify the CPU at runtime and use suitable + CPUVEC_SETUP_subdir macros to select the function pointers for it. + + iii) For the x86s, add to the "$tmp_prefix" setups in configure.in + which abbreviates subdirectory names to fit an 8.3 filesystem. + (No need to restrict to 8.3, just ensure uniqueness when + truncated.) + + +* The configure system + +** Installing tools + +The current versions of automake, autoconf and libtool in use can be +checked in the ChangeLog. Look for "Update to ...". Patches may have +been applied, look for "Regenerate ...". + +The GMP build system is in places somewhat dependent on the internals +of the build tools. Obviously that's avoided as much as possible, but +where it can't it creates a problem when upgrading or attempting to +use different tools versions. + +** Updating gmp + +The following files need to be updated when going to a new version of +the build tools. Unfortunately the tools generally don't identify +when an out-of-date version is present. + +aclocal.m4 is updated by running "aclocal". (Only needed for a new +automake or libtool.) + +INSTALL.autoconf can be copied from INSTALL in autoconf. + +ltmain.sh comes from libtool. Remove it and run "libtoolize --copy", +or just copy the file by hand. + +texinfo.tex can be updated from ftp.gnu.org. Check it still works +with "make gmp.dvi", "make gmp.ps" and "make gmp.pdf". + +configfsf.guess and configfsf.sub can be updated from ftp.gnu.org (or +from the "config" cvs module at subversions.gnu.org). The gmp +config.guess and config.sub wrappers are supposed to make such an +update fairly painless. + +depcomp from automake is not needed because configure.in specifies +automake with "no-dependencies". + +** How it works + +During development: + + Input files Tool Output files + --------------------------------------------------------- + + aclocal + $prefix/share/aclocal*/*.m4 ----------------> aclocal.m4 + + + configure.in \ autoconf + aclocal.m4 / -----------------------------> configure + + + */Makefile.am \ automake + configure.in | ----------------------------> Makefile.in + aclocal.m4 / + + configure.in \ autoheader + aclocal.m4 / -----------------------------> config.in + +At build time: + + Input files Tool Output files + -------------------------------------------- + + */Makefile.in \ configure / */Makefile + config.in | -------------> | config.h + gmp-h.in / | config.m4 + | gmp.h + \ fat.h (fat binary build only) + +When configured with --enable-maintainer-mode the Makefiles include +rules to re-run the necessary tools if the input files are changed. +This can end up running a lot more things than are really necessary. + +If a build tree is in too much of a mess for those rules to work +properly then a bootstrap can be done from the source directory with + + aclocal + autoconf + automake + autoheader + +The autom4te.cache directory is created by autoconf to save some work +in subsequent automake or autoheader runs. It's recreated +automatically if removed, it doesn't get distributed. + +** C++ configuration + +It's intended that the contents of libgmp.la won't vary according to +whether --enable-cxx is selected. This means that if C++ shared +libraries don't work properly then a shared+static with --disable-cxx +can be done for the C parts, then a static-only with --enable-cxx to +get libgmpxx. + +libgmpxx.la uses some internals from libgmp.la, in order to share code +between C and C++. It's intended that libgmpxx can only be expected +to work with libgmp from the same version of GMP. If some of the +shared internals change their interface, then it's proposed to rename +them, for instance __gmp_doprint2 or the like, so as to provoke link +errors rather than mysterious failures from a mismatch. + +* Development setups + +** General + +--disable-shared will make builds go much faster, though of course +shared or shared+static should be tested too. + +--prefix to a dummy directory followed by "make install" will show +what's installed. + +"make check" acts on the libgmp just built, and will ignore any other +/usr/lib/libgmp, or at least it should do. Libtool does various hairy +things to ensure it hits the just-built library. + +** Long long limb testing + +On systems where gcc supports long long, but a limb is normally just a +long, the following can be used to force long long for testing +purposes. It will probably run quite slowly. + + ./configure --host=none ABI=longlong + +** Function argument conversions + +When using gcc, configuring with something like + + ./configure CFLAGS="-g -Wall -Wconversion -Wno-sign-compare" + +can show where function parameters are being converted due to having +function prototypes available, which won't happen in a K&R compiler. +Doing this in combination with the long long limb setups above is +good. + +Conversions between int and long aren't warned about by gcc when +they're the same size, which is unfortunate because casts should be +used in such cases, for the benefit of K&R compilers with int!=long +and where the difference matters in function calls. + +* Other Notes + +** Compatibility + +compat.c is the home of functions retained for binary compatibility, + but now done by other means (like a macro). + +struct __mpz_struct etc - this must be retained for C++ compatibility. + C++ applications defining functions taking mpz_t etc parameters + will get this in the mangled name because C++ "sees though" the + typedef mpz_t to the underlying struct. + +__gmpn - note that glibc defines some __mpn symbols, old versions of + some mpn routines, which it uses for floating point printfs. + + + + +Local variables: +mode: outline +fill-column: 70 +End: +/* eof doc/configuration */ diff --git a/gmp-6.3.0/doc/fdl-1.3.texi b/gmp-6.3.0/doc/fdl-1.3.texi new file mode 100644 index 0000000..05804ee --- /dev/null +++ b/gmp-6.3.0/doc/fdl-1.3.texi @@ -0,0 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000-2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{https://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/gmp-6.3.0/doc/gmp.info b/gmp-6.3.0/doc/gmp.info new file mode 100644 index 0000000..91caf89 --- /dev/null +++ b/gmp-6.3.0/doc/gmp.info @@ -0,0 +1,179 @@ +This is gmp.info, produced by makeinfo version 6.7 from gmp.texi. + +This manual describes how to install and use the GNU multiple precision +arithmetic library, version 6.3.0. + + Copyright 1991, 1993-2016, 2018-2020 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and +with the Back-Cover Texts being "You have freedom to copy and modify +this GNU Manual, like GNU software". A copy of the license is included +in *note GNU Free Documentation License::. +INFO-DIR-SECTION GNU libraries +START-INFO-DIR-ENTRY +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +END-INFO-DIR-ENTRY + + +Indirect: +gmp.info-1: 863 +gmp.info-2: 301246 + +Tag Table: +(Indirect) +Node: Top863 +Node: Copying2941 +Node: Introduction to GMP5288 +Node: Installing GMP8006 +Node: Build Options8738 +Node: ABI and ISA24450 +Node: Notes for Package Builds34296 +Node: Notes for Particular Systems37383 +Node: Known Build Problems45134 +Node: Performance optimization48667 +Node: GMP Basics49795 +Node: Headers and Libraries50443 +Node: Nomenclature and Types52054 +Node: Function Classes56262 +Node: Variable Conventions57797 +Node: Parameter Conventions60151 +Node: Memory Management62103 +Node: Reentrancy63231 +Node: Useful Macros and Constants65099 +Node: Compatibility with older versions66090 +Node: Demonstration Programs67000 +Node: Efficiency68859 +Node: Debugging76461 +Node: Profiling83236 +Node: Autoconf87227 +Node: Emacs89008 +Node: Reporting Bugs89614 +Node: Integer Functions92311 +Node: Initializing Integers93087 +Node: Assigning Integers95463 +Node: Simultaneous Integer Init & Assign97076 +Node: Converting Integers98723 +Node: Integer Arithmetic101663 +Node: Integer Division103399 +Node: Integer Exponentiation110158 +Node: Integer Roots111655 +Node: Number Theoretic Functions113372 +Node: Integer Comparisons121149 +Node: Integer Logic and Bit Fiddling122587 +Node: I/O of Integers125385 +Node: Integer Random Numbers128378 +Node: Integer Import and Export131002 +Node: Miscellaneous Integer Functions135018 +Node: Integer Special Functions136932 +Node: Rational Number Functions141105 +Node: Initializing Rationals142298 +Node: Rational Conversions144771 +Node: Rational Arithmetic146793 +Node: Comparing Rationals148205 +Node: Applying Integer Functions149674 +Node: I/O of Rationals151380 +Node: Floating-point Functions153739 +Node: Initializing Floats156790 +Node: Assigning Floats160882 +Node: Simultaneous Float Init & Assign163472 +Node: Converting Floats165022 +Node: Float Arithmetic168287 +Node: Float Comparison170440 +Node: I/O of Floats172011 +Node: Miscellaneous Float Functions174700 +Node: Low-level Functions176702 +Node: Random Number Functions210955 +Node: Random State Initialization212023 +Node: Random State Seeding214889 +Node: Random State Miscellaneous216289 +Node: Formatted Output216931 +Node: Formatted Output Strings217176 +Node: Formatted Output Functions222572 +Node: C++ Formatted Output226636 +Node: Formatted Input229337 +Node: Formatted Input Strings229573 +Node: Formatted Input Functions234233 +Node: C++ Formatted Input237202 +Node: C++ Class Interface239105 +Node: C++ Interface General240056 +Node: C++ Interface Integers243125 +Node: C++ Interface Rationals247358 +Node: C++ Interface Floats251382 +Node: C++ Interface Random Numbers257398 +Node: C++ Interface Limitations259798 +Node: Custom Allocation263373 +Node: Language Bindings267592 +Node: Algorithms270905 +Node: Multiplication Algorithms271605 +Node: Basecase Multiplication272694 +Node: Karatsuba Multiplication274602 +Node: Toom 3-Way Multiplication278226 +Node: Toom 4-Way Multiplication284650 +Node: Higher degree Toom'n'half286028 +Node: FFT Multiplication287316 +Node: Other Multiplication292651 +Node: Unbalanced Multiplication295125 +Node: Division Algorithms295913 +Node: Single Limb Division296292 +Node: Basecase Division299180 +Node: Divide and Conquer Division301246 +Node: Block-Wise Barrett Division303314 +Node: Exact Division303966 +Node: Exact Remainder307130 +Node: Small Quotient Division309380 +Node: Greatest Common Divisor Algorithms310978 +Node: Binary GCD311275 +Node: Lehmer's Algorithm314127 +Node: Subquadratic GCD316363 +Node: Extended GCD318833 +Node: Jacobi Symbol320152 +Node: Powering Algorithms322061 +Node: Normal Powering Algorithm322324 +Node: Modular Powering Algorithm322852 +Node: Root Extraction Algorithms323634 +Node: Square Root Algorithm323949 +Node: Nth Root Algorithm326090 +Node: Perfect Square Algorithm326875 +Node: Perfect Power Algorithm328962 +Node: Radix Conversion Algorithms329583 +Node: Binary to Radix329959 +Node: Radix to Binary333580 +Node: Other Algorithms335668 +Node: Prime Testing Algorithm336020 +Node: Factorial Algorithm337204 +Node: Binomial Coefficients Algorithm339606 +Node: Fibonacci Numbers Algorithm340500 +Node: Lucas Numbers Algorithm342974 +Node: Random Number Algorithms343695 +Node: Assembly Coding345815 +Node: Assembly Code Organisation346775 +Node: Assembly Basics347742 +Node: Assembly Carry Propagation348892 +Node: Assembly Cache Handling350722 +Node: Assembly Functional Units352883 +Node: Assembly Floating Point354502 +Node: Assembly SIMD Instructions358281 +Node: Assembly Software Pipelining359263 +Node: Assembly Loop Unrolling360324 +Node: Assembly Writing Guide362539 +Node: Internals365304 +Node: Integer Internals365816 +Node: Rational Internals368282 +Node: Float Internals369520 +Node: Raw Output Internals376925 +Node: C++ Interface Internals378120 +Node: Contributors381441 +Node: References387669 +Node: GNU Free Documentation License393588 +Node: Concept Index418730 +Node: Function Index466824 + +End Tag Table + + +Local Variables: +coding: iso-8859-1 +End: diff --git a/gmp-6.3.0/doc/gmp.info-1 b/gmp-6.3.0/doc/gmp.info-1 new file mode 100644 index 0000000..a30265d --- /dev/null +++ b/gmp-6.3.0/doc/gmp.info-1 @@ -0,0 +1,7025 @@ +This is gmp.info, produced by makeinfo version 6.7 from gmp.texi. + +This manual describes how to install and use the GNU multiple precision +arithmetic library, version 6.3.0. + + Copyright 1991, 1993-2016, 2018-2020 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and +with the Back-Cover Texts being "You have freedom to copy and modify +this GNU Manual, like GNU software". A copy of the license is included +in *note GNU Free Documentation License::. +INFO-DIR-SECTION GNU libraries +START-INFO-DIR-ENTRY +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +END-INFO-DIR-ENTRY + + +File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) + +GNU MP +****** + +This manual describes how to install and use the GNU multiple precision +arithmetic library, version 6.3.0. + + Copyright 1991, 1993-2016, 2018-2020 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and +with the Back-Cover Texts being "You have freedom to copy and modify +this GNU Manual, like GNU software". A copy of the license is included +in *note GNU Free Documentation License::. + +* Menu: + +* Copying:: GMP Copying Conditions (LGPL). +* Introduction to GMP:: Brief introduction to GNU MP. +* Installing GMP:: How to configure and compile the GMP library. +* GMP Basics:: What every GMP user should know. +* Reporting Bugs:: How to usefully report bugs. +* Integer Functions:: Functions for arithmetic on signed integers. +* Rational Number Functions:: Functions for arithmetic on rational numbers. +* Floating-point Functions:: Functions for arithmetic on floats. +* Low-level Functions:: Fast functions for natural numbers. +* Random Number Functions:: Functions for generating random numbers. +* Formatted Output:: 'printf' style output. +* Formatted Input:: 'scanf' style input. +* C++ Class Interface:: Class wrappers around GMP types. +* Custom Allocation:: How to customize the internal allocation. +* Language Bindings:: Using GMP from other languages. +* Algorithms:: What happens behind the scenes. +* Internals:: How values are represented behind the scenes. + +* Contributors:: Who brings you this library? +* References:: Some useful papers and books to read. +* GNU Free Documentation License:: +* Concept Index:: +* Function Index:: + + +File: gmp.info, Node: Copying, Next: Introduction to GMP, Prev: Top, Up: Top + +GNU MP Copying Conditions +************************* + +This library is "free"; this means that everyone is free to use it and +free to redistribute it on a free basis. The library is not in the +public domain; it is copyrighted and there are restrictions on its +distribution, but these restrictions are designed to permit everything +that a good cooperating citizen would want to do. What is not allowed +is to try to prevent others from further sharing any version of this +library that they might get from you. + + Specifically, we want to make sure that you have the right to give +away copies of the library, that you receive source code or else can get +it if you want it, that you can change this library or use pieces of it +in new free programs, and that you know you can do these things. + + To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the GNU MP library, you must give the recipients all the +rights that you have. You must make sure that they, too, receive or can +get the source code. And you must tell them their rights. + + Also, for our own protection, we must make certain that everyone +finds out that there is no warranty for the GNU MP library. If it is +modified by someone else and passed on, we want their recipients to know +that what they have is not what we distributed, so that any problems +introduced by others will not reflect on our reputation. + + More precisely, the GNU MP library is dual licensed, under the +conditions of the GNU Lesser General Public License version 3 (see +'COPYING.LESSERv3'), or the GNU General Public License version 2 (see +'COPYINGv2'). This is the recipient's choice, and the recipient also +has the additional option of applying later versions of these licenses. +(The reason for this dual licensing is to make it possible to use the +library with programs which are licensed under GPL version 2, but which +for historical or other reasons do not allow use under later versions of +the GPL.) + + Programs which are not part of the library itself, such as +demonstration programs and the GMP testsuite, are licensed under the +terms of the GNU General Public License version 3 (see 'COPYINGv3'), or +any later version. + + +File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top + +1 Introduction to GNU MP +************************ + +GNU MP is a portable library written in C for arbitrary precision +arithmetic on integers, rational numbers, and floating-point numbers. +It aims to provide the fastest possible arithmetic for all applications +that need higher precision than is directly supported by the basic C +types. + + Many applications use just a few hundred bits of precision; but some +applications may need thousands or even millions of bits. GMP is +designed to give good performance for both, by choosing algorithms based +on the sizes of the operands, and by carefully keeping the overhead at a +minimum. + + The speed of GMP is achieved by using fullwords as the basic +arithmetic type, by using sophisticated algorithms, by including +carefully optimized assembly code for the most common inner loops for +many different CPUs, and by a general emphasis on speed (as opposed to +simplicity or elegance). + + There is assembly code for these CPUs: ARM Cortex-A9, Cortex-A15, and +generic ARM, DEC Alpha 21064, 21164, and 21264, AMD K8 and K10 (sold +under many brands, e.g. Athlon64, Phenom, Opteron), Bulldozer, and +Bobcat, Intel Pentium, Pentium Pro/II/III, Pentium 4, Core2, Nehalem, +Sandy bridge, Haswell, generic x86, Intel IA-64, Motorola/IBM PowerPC 32 +and 64 such as POWER970, POWER5, POWER6, and POWER7, MIPS 32-bit and +64-bit, SPARC 32-bit and 64-bit with special support for all UltraSPARC +models. There is also assembly code for many obsolete CPUs. + +For up-to-date information on GMP, please see the GMP web pages at + + + +The latest version of the library is available at + + + + Many sites around the world mirror 'ftp.gnu.org', please use a mirror +near you, see for a full list. + + There are three public mailing lists of interest. One for release +announcements, one for general questions and discussions about usage of +the GMP library and one for bug reports. For more information, see + + . + + The proper place for bug reports is . See *note +Reporting Bugs:: for information about reporting bugs. + + +1.1 How to use this Manual +========================== + +Everyone should read *note GMP Basics::. If you need to install the +library yourself, then read *note Installing GMP::. If you have a +system with multiple ABIs, then read *note ABI and ISA::, for the +compiler options that must be used on applications. + + The rest of the manual can be used for later reference, although it +is probably a good idea to glance through it. + + +File: gmp.info, Node: Installing GMP, Next: GMP Basics, Prev: Introduction to GMP, Up: Top + +2 Installing GMP +**************** + +GMP has an autoconf/automake/libtool based configuration system. On a +Unix-like system a basic build can be done with + + ./configure + make + +Some self-tests can be run with + + make check + +And you can install (under '/usr/local' by default) with + + make install + + If you experience problems, please report them to +. See *note Reporting Bugs::, for information on +what to include in useful bug reports. + +* Menu: + +* Build Options:: +* ABI and ISA:: +* Notes for Package Builds:: +* Notes for Particular Systems:: +* Known Build Problems:: +* Performance optimization:: + + +File: gmp.info, Node: Build Options, Next: ABI and ISA, Prev: Installing GMP, Up: Installing GMP + +2.1 Build Options +================= + +All the usual autoconf configure options are available, run './configure +--help' for a summary. The file 'INSTALL.autoconf' has some generic +installation information too. + +Tools + 'configure' requires various Unix-like tools. See *note Notes for + Particular Systems::, for some options on non-Unix systems. + + It might be possible to build without the help of 'configure', + certainly all the code is there, but unfortunately you'll be on + your own. + +Build Directory + To compile in a separate build directory, 'cd' to that directory, + and prefix the configure command with the path to the GMP source + directory. For example + + cd /my/build/dir + /my/sources/gmp-6.3.0/configure + + Not all 'make' programs have the necessary features ('VPATH') to + support this. In particular, SunOS and Slowaris 'make' have bugs + that make them unable to build in a separate directory. Use GNU + 'make' instead. + +'--prefix' and '--exec-prefix' + The '--prefix' option can be used in the normal way to direct GMP + to install under a particular tree. The default is '/usr/local'. + + '--exec-prefix' can be used to direct architecture-dependent files + like 'libgmp.a' to a different location. This can be used to share + architecture-independent parts like the documentation, but separate + the dependent parts. Note however that 'gmp.h' is + architecture-dependent since it encodes certain aspects of + 'libgmp', so it will be necessary to ensure both '$prefix/include' + and '$exec_prefix/include' are available to the compiler. + +'--disable-shared', '--disable-static' + By default both shared and static libraries are built (where + possible), but one or other can be disabled. Shared libraries + result in smaller executables and permit code sharing between + separate running processes, but on some CPUs are slightly slower, + having a small cost on each function call. + +Native Compilation, '--build=CPU-VENDOR-OS' + For normal native compilation, the system can be specified with + '--build'. By default './configure' uses the output from running + './config.guess'. On some systems './config.guess' can determine + the exact CPU type, on others it will be necessary to give it + explicitly. For example, + + ./configure --build=ultrasparc-sun-solaris2.7 + + In all cases the 'OS' part is important, since it controls how + libtool generates shared libraries. Running './config.guess' is + the simplest way to see what it should be, if you don't know + already. + +Cross Compilation, '--host=CPU-VENDOR-OS' + When cross-compiling, the system used for compiling is given by + '--build' and the system where the library will run is given by + '--host'. For example when using a FreeBSD Athlon system to build + GNU/Linux m68k binaries, + + ./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu + + Compiler tools are sought first with the host system type as a + prefix. For example 'm68k-mac-linux-gnu-ranlib' is tried, then + plain 'ranlib'. This makes it possible for a set of + cross-compiling tools to co-exist with native tools. The prefix is + the argument to '--host', and this can be an alias, such as + 'm68k-linux'. But note that tools don't have to be set up this + way, it's enough to just have a 'PATH' with a suitable + cross-compiling 'cc' etc. + + Compiling for a different CPU in the same family as the build + system is a form of cross-compilation, though very possibly this + would merely be special options on a native compiler. In any case + './configure' avoids depending on being able to run code on the + build system, which is important when creating binaries for a newer + CPU since they very possibly won't run on the build system. + + In all cases the compiler must be able to produce an executable (of + whatever format) from a standard C 'main'. Although only object + files will go to make up 'libgmp', './configure' uses linking tests + for various purposes, such as determining what functions are + available on the host system. + + Currently a warning is given unless an explicit '--build' is used + when cross-compiling, because it may not be possible to correctly + guess the build system type if the 'PATH' has only a + cross-compiling 'cc'. + + Note that the '--target' option is not appropriate for GMP. It's + for use when building compiler tools, with '--host' being where + they will run, and '--target' what they'll produce code for. + Ordinary programs or libraries like GMP are only interested in the + '--host' part, being where they'll run. (Some past versions of GMP + used '--target' incorrectly.) + +CPU types + In general, if you want a library that runs as fast as possible, + you should configure GMP for the exact CPU type your system uses. + However, this may mean the binaries won't run on older members of + the family, and might run slower on other members, older or newer. + The best idea is always to build GMP for the exact machine type you + intend to run it on. + + The following CPUs have specific support. See 'configure.ac' for + details of what code and compiler options they select. + + * Alpha: alpha, alphaev5, alphaev56, alphapca56, alphapca57, + alphaev6, alphaev67, alphaev68, alphaev7 + + * Cray: c90, j90, t90, sv1 + + * HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w, hppa64 + + * IA-64: ia64, itanium, itanium2 + + * MIPS: mips, mips3, mips64 + + * Motorola: m68k, m68000, m68010, m68020, m68030, m68040, + m68060, m68302, m68360, m88k, m88110 + + * POWER: power, power1, power2, power2sc + + * PowerPC: powerpc, powerpc64, powerpc401, powerpc403, + powerpc405, powerpc505, powerpc601, powerpc602, powerpc603, + powerpc603e, powerpc604, powerpc604e, powerpc620, powerpc630, + powerpc740, powerpc7400, powerpc7450, powerpc750, powerpc801, + powerpc821, powerpc823, powerpc860, powerpc970 + + * SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9, + ultrasparc, ultrasparc2, ultrasparc2i, ultrasparc3, sparc64 + + * x86 family: i386, i486, i586, pentium, pentiummmx, pentiumpro, + pentium2, pentium3, pentium4, k6, k62, k63, athlon, amd64, + viac3, viac32 + + * Other: arm, sh, sh2, vax, + + CPUs not listed will use generic C code. + +Generic C Build + If some of the assembly code causes problems, or if otherwise + desired, the generic C code can be selected with the configure + '--disable-assembly'. + + Note that this will run quite slowly, but it should be portable and + should at least make it possible to get something running if all + else fails. + +Fat binary, '--enable-fat' + Using '--enable-fat' selects a "fat binary" build on x86, where + optimized low level subroutines are chosen at runtime according to + the CPU detected. This means more code, but gives good performance + on all x86 chips. (This option might become available for more + architectures in the future.) + +'ABI' + On some systems GMP supports multiple ABIs (application binary + interfaces), meaning data type sizes and calling conventions. By + default GMP chooses the best ABI available, but a particular ABI + can be selected. For example + + ./configure --host=mips64-sgi-irix6 ABI=n32 + + See *note ABI and ISA::, for the available choices on relevant + CPUs, and what applications need to do. + +'CC', 'CFLAGS' + By default the C compiler used is chosen from among some likely + candidates, with 'gcc' normally preferred if it's present. The + usual 'CC=whatever' can be passed to './configure' to choose + something different. + + For various systems, default compiler flags are set based on the + CPU and compiler. The usual 'CFLAGS="-whatever"' can be passed to + './configure' to use something different or to set good flags for + systems GMP doesn't otherwise know. + + The 'CC' and 'CFLAGS' used are printed during './configure', and + can be found in each generated 'Makefile'. This is the easiest way + to check the defaults when considering changing or adding + something. + + Note that when 'CC' and 'CFLAGS' are specified on a system + supporting multiple ABIs it's important to give an explicit + 'ABI=whatever', since GMP can't determine the ABI just from the + flags and won't be able to select the correct assembly code. + + If just 'CC' is selected then normal default 'CFLAGS' for that + compiler will be used (if GMP recognises it). For example 'CC=gcc' + can be used to force the use of GCC, with default flags (and + default ABI). + +'CPPFLAGS' + Any flags like '-D' defines or '-I' includes required by the + preprocessor should be set in 'CPPFLAGS' rather than 'CFLAGS'. + Compiling is done with both 'CPPFLAGS' and 'CFLAGS', but + preprocessing uses just 'CPPFLAGS'. This distinction is because + most preprocessors won't accept all the flags the compiler does. + Preprocessing is done separately in some configure tests. + +'CC_FOR_BUILD' + Some build-time programs are compiled and run to generate + host-specific data tables. 'CC_FOR_BUILD' is the compiler used for + this. It doesn't need to be in any particular ABI or mode, it + merely needs to generate executables that can run. The default is + to try the selected 'CC' and some likely candidates such as 'cc' + and 'gcc', looking for something that works. + + No flags are used with 'CC_FOR_BUILD' because a simple invocation + like 'cc foo.c' should be enough. If some particular options are + required they can be included as for instance 'CC_FOR_BUILD="cc + -whatever"'. + +C++ Support, '--enable-cxx' + C++ support in GMP can be enabled with '--enable-cxx', in which + case a C++ compiler will be required. As a convenience + '--enable-cxx=detect' can be used to enable C++ support only if a + compiler can be found. The C++ support consists of a library + 'libgmpxx.la' and header file 'gmpxx.h' (*note Headers and + Libraries::). + + A separate 'libgmpxx.la' has been adopted rather than having C++ + objects within 'libgmp.la' in order to ensure dynamic linked C + programs aren't bloated by a dependency on the C++ standard + library, and to avoid any chance that the C++ compiler could be + required when linking plain C programs. + + 'libgmpxx.la' will use certain internals from 'libgmp.la' and can + only be expected to work with 'libgmp.la' from the same GMP + version. Future changes to the relevant internals will be + accompanied by renaming, so a mismatch will cause unresolved + symbols rather than perhaps mysterious misbehaviour. + + In general 'libgmpxx.la' will be usable only with the C++ compiler + that built it, since name mangling and runtime support are usually + incompatible between different compilers. + +'CXX', 'CXXFLAGS' + When C++ support is enabled, the C++ compiler and its flags can be + set with variables 'CXX' and 'CXXFLAGS' in the usual way. The + default for 'CXX' is the first compiler that works from a list of + likely candidates, with 'g++' normally preferred when available. + The default for 'CXXFLAGS' is to try 'CFLAGS', 'CFLAGS' without + '-g', then for 'g++' either '-g -O2' or '-O2', or for other + compilers '-g' or nothing. Trying 'CFLAGS' this way is convenient + when using 'gcc' and 'g++' together, since the flags for 'gcc' will + usually suit 'g++'. + + It's important that the C and C++ compilers match, meaning their + startup and runtime support routines are compatible and that they + generate code in the same ABI (if there's a choice of ABIs on the + system). './configure' isn't currently able to check these things + very well itself, so for that reason '--disable-cxx' is the + default, to avoid a build failure due to a compiler mismatch. + Perhaps this will change in the future. + + Incidentally, it's normally not good enough to set 'CXX' to the + same as 'CC'. Although 'gcc' for instance recognises 'foo.cc' as + C++ code, only 'g++' will invoke the linker the right way when + building an executable or shared library from C++ object files. + +Temporary Memory, '--enable-alloca=' + GMP allocates temporary workspace using one of the following three + methods, which can be selected with for instance + '--enable-alloca=malloc-reentrant'. + + * 'alloca' - C library or compiler builtin. + * 'malloc-reentrant' - the heap, in a re-entrant fashion. + * 'malloc-notreentrant' - the heap, with global variables. + + For convenience, the following choices are also available. + '--disable-alloca' is the same as 'no'. + + * 'yes' - a synonym for 'alloca'. + * 'no' - a synonym for 'malloc-reentrant'. + * 'reentrant' - 'alloca' if available, otherwise + 'malloc-reentrant'. This is the default. + * 'notreentrant' - 'alloca' if available, otherwise + 'malloc-notreentrant'. + + 'alloca' is reentrant and fast, and is recommended. It actually + allocates just small blocks on the stack; larger ones use + malloc-reentrant. + + 'malloc-reentrant' is, as the name suggests, reentrant and thread + safe, but 'malloc-notreentrant' is faster and should be used if + reentrancy is not required. + + The two malloc methods in fact use the memory allocation functions + selected by 'mp_set_memory_functions', these being 'malloc' and + friends by default. *Note Custom Allocation::. + + An additional choice '--enable-alloca=debug' is available, to help + when debugging memory related problems (*note Debugging::). + +FFT Multiplication, '--disable-fft' + By default multiplications are done using Karatsuba, 3-way Toom, + higher degree Toom, and Fermat FFT. The FFT is only used on large + to very large operands and can be disabled to save code size if + desired. + +Assertion Checking, '--enable-assert' + This option enables some consistency checking within the library. + This can be of use while debugging, *note Debugging::. + +Execution Profiling, '--enable-profiling=prof/gprof/instrument' + Enable profiling support, in one of various styles, *note + Profiling::. + +'MPN_PATH' + Various assembly versions of each mpn subroutines are provided. + For a given CPU, a search is made through a path to choose a + version of each. For example 'sparcv8' has + + MPN_PATH="sparc32/v8 sparc32 generic" + + which means look first for v8 code, then plain sparc32 (which is + v7), and finally fall back on generic C. Knowledgeable users with + special requirements can specify a different path. Normally this + is completely unnecessary. + +Documentation + The source for the document you're now reading is 'doc/gmp.texi', + in Texinfo format, see *note Texinfo: (texinfo)Top. + + Info format 'doc/gmp.info' is included in the distribution. The + usual automake targets are available to make PostScript, DVI, PDF + and HTML (these will require various TeX and Texinfo tools). + + DocBook and XML can be generated by the Texinfo 'makeinfo' program + too, see *note Options for 'makeinfo': (texinfo)makeinfo options. + + Some supplementary notes can also be found in the 'doc' + subdirectory. + + +File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP + +2.2 ABI and ISA +=============== + +ABI (Application Binary Interface) refers to the calling conventions +between functions, meaning what registers are used and what sizes the +various C data types are. ISA (Instruction Set Architecture) refers to +the instructions and registers a CPU has available. + + Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI defined, +the latter for compatibility with older CPUs in the family. GMP +supports some CPUs like this in both ABIs. In fact within GMP 'ABI' +means a combination of chip ABI, plus how GMP chooses to use it. For +example in some 32-bit ABIs, GMP may support a limb as either a 32-bit +'long' or a 64-bit 'long long'. + + By default GMP chooses the best ABI available for a given system, and +this generally gives significantly greater speed. But an ABI can be +chosen explicitly to make GMP compatible with other libraries, or +particular application requirements. For example, + + ./configure ABI=32 + + In all cases it's vital that all object code used in a given program +is compiled for the same ABI. + + Usually a limb is implemented as a 'long'. When a 'long long' limb +is used this is encoded in the generated 'gmp.h'. This is convenient +for applications, but it does mean that 'gmp.h' will vary, and can't be +just copied around. 'gmp.h' remains compiler independent though, since +all compilers for a particular ABI will be expected to use the same limb +type. + + Currently no attempt is made to follow whatever conventions a system +has for installing library or header files built for a particular ABI. +This will probably only matter when installing multiple builds of GMP, +and it might be as simple as configuring with a special 'libdir', or it +might require more than that. Note that builds for different ABIs need +to be done separately, with a fresh './configure' and 'make' each. + + +AMD64 ('x86_64') + On AMD64 systems supporting both 32-bit and 64-bit modes for + applications, the following ABI choices are available. + + 'ABI=64' + The 64-bit ABI uses 64-bit limbs and pointers and makes full + use of the chip architecture. This is the default. + Applications will usually not need special compiler flags, but + for reference the option is + + gcc -m64 + + 'ABI=32' + The 32-bit ABI is the usual i386 conventions. This will be + slower, and is not recommended except for inter-operating with + other code not yet 64-bit capable. Applications must be + compiled with + + gcc -m32 + + (In GCC 2.95 and earlier there's no '-m32' option, it's the + only mode.) + + 'ABI=x32' + The x32 ABI uses 64-bit limbs but 32-bit pointers. Like the + 64-bit ABI, it makes full use of the chip's arithmetic + capabilities. This ABI is not supported by all operating + systems. + + gcc -mx32 + + +HPPA 2.0 ('hppa2.0*', 'hppa64') + 'ABI=2.0w' + The 2.0w ABI uses 64-bit limbs and pointers and is available + on HP-UX 11 or up. Applications must be compiled with + + gcc [built for 2.0w] + cc +DD64 + + 'ABI=2.0n' + The 2.0n ABI means the 32-bit HPPA 1.0 ABI and all its normal + calling conventions, but with 64-bit instructions permitted + within functions. GMP uses a 64-bit 'long long' for a limb. + This ABI is available on hppa64 GNU/Linux and on HP-UX 10 or + higher. Applications must be compiled with + + gcc [built for 2.0n] + cc +DA2.0 +e + + Note that current versions of GCC (e.g. 3.2) don't generate + 64-bit instructions for 'long long' operations and so may be + slower than for 2.0w. (The GMP assembly code is the same + though.) + + 'ABI=1.0' + HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit + HPPA 1.0 ABI. No special compiler options are needed for + applications. + + All three ABIs are available for CPU types 'hppa2.0w', 'hppa2.0' + and 'hppa64', but for CPU type 'hppa2.0n' only 2.0n or 1.0 are + considered. + + Note that GCC on HP-UX has no options to choose between 2.0n and + 2.0w modes, unlike HP 'cc'. Instead it must be built for one or + the other ABI. GMP will detect how it was built, and skip to the + corresponding 'ABI'. + + +IA-64 under HP-UX ('ia64*-*-hpux*', 'itanium*-*-hpux*') + HP-UX supports two ABIs for IA-64. GMP performance is the same in + both. + + 'ABI=32' + In the 32-bit ABI, pointers, 'int's and 'long's are 32 bits + and GMP uses a 64 bit 'long long' for a limb. Applications + can be compiled without any special flags since this ABI is + the default in both HP C and GCC, but for reference the flags + are + + gcc -milp32 + cc +DD32 + + 'ABI=64' + In the 64-bit ABI, 'long's and pointers are 64 bits and GMP + uses a 'long' for a limb. Applications must be compiled with + + gcc -mlp64 + cc +DD64 + + On other IA-64 systems, GNU/Linux for instance, 'ABI=64' is the + only choice. + + +MIPS under IRIX 6 ('mips*-*-irix[6789]') + IRIX 6 always has a 64-bit MIPS 3 or better CPU, and supports ABIs + o32, n32, and 64. n32 or 64 are recommended, and GMP performance + will be the same in each. The default is n32. + + 'ABI=o32' + The o32 ABI is 32-bit pointers and integers, and no 64-bit + operations. GMP will be slower than in n32 or 64, this option + only exists to support old compilers, e.g. GCC 2.7.2. + Applications can be compiled with no special flags on an old + compiler, or on a newer compiler with + + gcc -mabi=32 + cc -32 + + 'ABI=n32' + The n32 ABI is 32-bit pointers and integers, but with a 64-bit + limb using a 'long long'. Applications must be compiled with + + gcc -mabi=n32 + cc -n32 + + 'ABI=64' + The 64-bit ABI is 64-bit pointers and integers. Applications + must be compiled with + + gcc -mabi=64 + cc -64 + + Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have + the necessary support for n32 or 64 and so only gets a 32-bit limb + and the MIPS 2 code. + + +PowerPC 64 ('powerpc64', 'powerpc620', 'powerpc630', 'powerpc970', 'power4', 'power5') + 'ABI=mode64' + The AIX 64 ABI uses 64-bit limbs and pointers and is the + default on PowerPC 64 '*-*-aix*' systems. Applications must + be compiled with + + gcc -maix64 + xlc -q64 + + On 64-bit GNU/Linux, BSD, and Mac OS X/Darwin systems, the + applications must be compiled with + + gcc -m64 + + 'ABI=mode32' + The 'mode32' ABI uses a 64-bit 'long long' limb but with the + chip still in 32-bit mode and using 32-bit calling + conventions. This is the default for systems where the true + 64-bit ABI is unavailable. No special compiler options are + typically needed for applications. This ABI is not available + under AIX. + + 'ABI=32' + This is the basic 32-bit PowerPC ABI, with a 32-bit limb. No + special compiler options are needed for applications. + + GMP's speed is greatest for the 'mode64' ABI, the 'mode32' ABI is + 2nd best. In 'ABI=32' only the 32-bit ISA is used and this doesn't + make full use of a 64-bit chip. + + +Sparc V9 ('sparc64', 'sparcv9', 'ultrasparc*') + 'ABI=64' + The 64-bit V9 ABI is available on the various BSD sparc64 + ports, recent versions of Sparc64 GNU/Linux, and Solaris 2.7 + and up (when the kernel is in 64-bit mode). GCC 3.2 or + higher, or Sun 'cc' is required. On GNU/Linux, depending on + the default 'gcc' mode, applications must be compiled with + + gcc -m64 + + On Solaris applications must be compiled with + + gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 + cc -xarch=v9 + + On the BSD sparc64 systems no special options are required, + since 64-bits is the only ABI available. + + 'ABI=32' + For the basic 32-bit ABI, GMP still uses as much of the V9 ISA + as it can. In the Sun documentation this combination is known + as "v8plus". On GNU/Linux, depending on the default 'gcc' + mode, applications may need to be compiled with + + gcc -m32 + + On Solaris, no special compiler options are required for + applications, though using something like the following is + recommended. ('gcc' 2.8 and earlier only support '-mv8' + though.) + + gcc -mv8plus + cc -xarch=v8plus + + GMP speed is greatest in 'ABI=64', so it's the default where + available. The speed is partly because there are extra registers + available and partly because 64-bits is considered the more + important case and has therefore had better code written for it. + + Don't be confused by the names of the '-m' and '-x' compiler + options, they're called 'arch' but effectively control both ABI and + ISA. + + On Solaris 2.6 and earlier, only 'ABI=32' is available since the + kernel doesn't save all registers. + + On Solaris 2.7 with the kernel in 32-bit mode, a normal native + build will reject 'ABI=64' because the resulting executables won't + run. 'ABI=64' can still be built if desired by making it look like + a cross-compile, for example + + ./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64 + + +File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP + +2.3 Notes for Package Builds +============================ + +GMP should present no great difficulties for packaging in a binary +distribution. + + Libtool is used to build the library and '-version-info' is set +appropriately, having started from '3:0:0' in GMP 3.0 (*note Library +interface versions: (libtool)Versioning.). + + The GMP 4 series will be upwardly binary compatible in each release +and will be upwardly binary compatible with all of the GMP 3 series. +Additional function interfaces may be added in each release, so on +systems where libtool versioning is not fully checked by the loader an +auxiliary mechanism may be needed to express that a dynamic linked +application depends on a new enough GMP. + + An auxiliary mechanism may also be needed to express that +'libgmpxx.la' (from '--enable-cxx', *note Build Options::) requires +'libgmp.la' from the same GMP version, since this is not done by the +libtool versioning, nor otherwise. A mismatch will result in unresolved +symbols from the linker, or perhaps the loader. + + When building a package for a CPU family, care should be taken to use +'--host' (or '--build') to choose the least common denominator among the +CPUs which might use the package. For example this might mean plain +'sparc' (meaning V7) for SPARCs. + + For x86s, '--enable-fat' sets things up for a fat binary build, +making a runtime selection of optimized low level routines. This is a +good choice for packaging to run on a range of x86 chips. + + Users who care about speed will want GMP built for their exact CPU +type, to make best use of the available optimizations. Providing a way +to suitably rebuild a package may be useful. This could be as simple as +making it possible for a user to omit '--build' (and '--host') so +'./config.guess' will detect the CPU. But a way to manually specify a +'--build' will be wanted for systems where './config.guess' is inexact. + + On systems with multiple ABIs, a packaged build will need to decide +which among the choices is to be provided, see *note ABI and ISA::. A +given run of './configure' etc will only build one ABI. If a second ABI +is also required then a second run of './configure' etc must be made, +starting from a clean directory tree ('make distclean'). + + As noted under "ABI and ISA", currently no attempt is made to follow +system conventions for install locations that vary with ABI, such as +'/usr/lib/sparcv9' for 'ABI=64' as opposed to '/usr/lib' for 'ABI=32'. +A package build can override 'libdir' and other standard variables as +necessary. + + Note that 'gmp.h' is a generated file, and will be architecture and +ABI dependent. When attempting to install two ABIs simultaneously it +will be important that an application compile gets the correct 'gmp.h' +for its desired ABI. If compiler include paths don't vary with ABI +options then it might be necessary to create a '/usr/include/gmp.h' +which tests preprocessor symbols and chooses the correct actual 'gmp.h'. + + +File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP + +2.4 Notes for Particular Systems +================================ + +AIX 3 and 4 + On systems '*-*-aix[34]*' shared libraries are disabled by default, + since some versions of the native 'ar' fail on the convenience + libraries used. A shared build can be attempted with + + ./configure --enable-shared --disable-static + + Note that the '--disable-static' is necessary because in a shared + build libtool makes 'libgmp.a' a symlink to 'libgmp.so', apparently + for the benefit of old versions of 'ld' which only recognise '.a', + but unfortunately this is done even if a fully functional 'ld' is + available. + +ARM + On systems 'arm*-*-*', versions of GCC up to and including 2.95.3 + have a bug in unsigned division, giving wrong results for some + operands. GMP './configure' will demand GCC 2.95.4 or later. + +Compaq C++ + Compaq C++ on OSF 5.1 has two flavours of 'iostream', a standard + one and an old pre-standard one (see 'man iostream_intro'). GMP + can only use the standard one, which unfortunately is not the + default but must be selected by defining '__USE_STD_IOSTREAM'. + Configure with for instance + + ./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM + +Floating Point Mode + On some systems, the hardware floating point has a control mode + which can set all operations to be done in a particular precision, + for instance single, double or extended on x86 systems (x87 + floating point). The GMP functions involving a 'double' cannot be + expected to operate to their full precision when the hardware is in + single precision mode. Of course this affects all code, including + application code, not just GMP. + +FreeBSD 7.x, 8.x, 9.0, 9.1, 9.2 + 'm4' in these releases of FreeBSD has an eval function which + ignores its 2nd and 3rd arguments, which makes it unsuitable for + '.asm' file processing. './configure' will detect the problem and + either abort or choose another m4 in the 'PATH'. The bug is fixed + in FreeBSD 9.3 and 10.0, so either upgrade or use GNU m4. Note + that the FreeBSD package system installs GNU m4 under the name + 'gm4', which GMP cannot guess. + +FreeBSD 7.x, 8.x, 9.x + GMP releases starting with 6.0 do not support 'ABI=32' on + FreeBSD/amd64 prior to release 10.0 of the system. The cause is a + broken 'limits.h', which GMP no longer works around. + +MS-DOS and MS Windows + On an MS-DOS system DJGPP can be used to build GMP, and on an MS + Windows system Cygwin, DJGPP and MINGW can be used. All three are + excellent ports of GCC and the various GNU tools. + + + + + + Microsoft also publishes an Interix "Services for Unix" which can + be used to build GMP on Windows (with a normal './configure'), but + it's not free software. + +MS Windows DLLs + On systems '*-*-cygwin*', '*-*-mingw*' and '*-*-pw32*' by default + GMP builds only a static library, but a DLL can be built instead + using + + ./configure --disable-static --enable-shared + + Static and DLL libraries can't both be built, since certain export + directives in 'gmp.h' must be different. + + A MINGW DLL build of GMP can be used with Microsoft C. Libtool + doesn't install a '.lib' format import library, but it can be + created with MS 'lib' as follows, and copied to the install + directory. Similarly for 'libmp' and 'libgmpxx'. + + cd .libs + lib /def:libgmp-3.dll.def /out:libgmp-3.lib + + MINGW uses the C runtime library 'msvcrt.dll' for I/O, so + applications wanting to use the GMP I/O routines must be compiled + with 'cl /MD' to do the same. If one of the other C runtime + library choices provided by MS C is desired then the suggestion is + to use the GMP string functions and confine I/O to the application. + +Motorola 68k CPU Types + 'm68k' is taken to mean 68000. 'm68020' or higher will give a + performance boost on applicable CPUs. 'm68360' can be used for + CPU32 series chips. 'm68302' can be used for "Dragonball" series + chips, though this is merely a synonym for 'm68000'. + +NetBSD 5.x + 'm4' in these releases of NetBSD has an eval function which ignores + its 2nd and 3rd arguments, which makes it unsuitable for '.asm' + file processing. './configure' will detect the problem and either + abort or choose another m4 in the 'PATH'. The bug is fixed in + NetBSD 6, so either upgrade or use GNU m4. Note that the NetBSD + package system installs GNU m4 under the name 'gm4', which GMP + cannot guess. + +OpenBSD 2.6 + 'm4' in this release of OpenBSD has a bug in 'eval' that makes it + unsuitable for '.asm' file processing. './configure' will detect + the problem and either abort or choose another m4 in the 'PATH'. + The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. + +Power CPU Types + In GMP, CPU types 'power*' and 'powerpc*' will each use + instructions not available on the other, so it's important to + choose the right one for the CPU that will be used. Currently GMP + has no assembly code support for using just the common instruction + subset. To get executables that run on both, the current + suggestion is to use the generic C code ('--disable-assembly'), + possibly with appropriate compiler options (like '-mcpu=common' for + 'gcc'). CPU 'rs6000' (which is not a CPU but a family of + workstations) is accepted by 'config.sub', but is currently + equivalent to '--disable-assembly'. + +Sparc CPU Types + 'sparcv8' or 'supersparc' on relevant systems will give a + significant performance increase over the V7 code selected by plain + 'sparc'. + +Sparc App Regs + The GMP assembly code for both 32-bit and 64-bit Sparc clobbers the + "application registers" 'g2', 'g3' and 'g4', the same way that the + GCC default '-mapp-regs' does (*note SPARC Options: (gcc)SPARC + Options.). + + This makes that code unsuitable for use with the special V9 + '-mcmodel=embmedany' (which uses 'g4' as a data segment pointer), + and for applications wanting to use those registers for special + purposes. In these cases the only suggestion currently is to build + GMP with '--disable-assembly' to avoid the assembly code. + +SunOS 4 + '/usr/bin/m4' lacks various features needed to process '.asm' + files, and instead './configure' will automatically use + '/usr/5bin/m4', which we believe is always available (if not then + use GNU m4). + +x86 CPU Types + 'i586', 'pentium' or 'pentiummmx' code is good for its intended P5 + Pentium chips, but quite slow when run on Intel P6 class chips + (PPro, P-II, P-III). 'i386' is a better choice when making + binaries that must run on both. + +x86 MMX and SSE2 Code + If the CPU selected has MMX code but the assembler doesn't support + it, a warning is given and non-MMX code is used instead. This will + be an inferior build, since the MMX code that's present is there + because it's faster than the corresponding plain integer code. The + same applies to SSE2. + + Old versions of 'gas' don't support MMX instructions, in particular + version 1.92.3 that comes with FreeBSD 2.2.8 or the more recent + OpenBSD 3.1 doesn't. + + Solaris 2.6 and 2.7 'as' generate incorrect object code for + register to register 'movq' instructions, and so can't be used for + MMX code. Install a recent 'gas' if MMX code is wanted on these + systems. + + +File: gmp.info, Node: Known Build Problems, Next: Performance optimization, Prev: Notes for Particular Systems, Up: Installing GMP + +2.5 Known Build Problems +======================== + +You might find more up-to-date information at . + +Compiler link options + The version of libtool currently in use rather aggressively strips + compiler options when linking a shared library. This will + hopefully be relaxed in the future, but for now if this is a + problem the suggestion is to create a little script to hide them, + and for instance configure with + + ./configure CC=gcc-with-my-options + +DJGPP ('*-*-msdosdjgpp*') + The DJGPP port of 'bash' 2.03 is unable to run the 'configure' + script, it exits silently, having died writing a preamble to + 'config.log'. Use 'bash' 2.04 or higher. + + 'make all' was found to run out of memory during the final + 'libgmp.la' link on one system tested, despite having 64MiB + available. Running 'make libgmp.la' directly helped, perhaps + recursing into the various subdirectories uses up memory. + +GNU binutils 'strip' prior to 2.12 + 'strip' from GNU binutils 2.11 and earlier should not be used on + the static libraries 'libgmp.a' and 'libmp.a' since it will discard + all but the last of multiple archive members with the same name, + like the three versions of 'init.o' in 'libgmp.a'. Binutils 2.12 + or higher can be used successfully. + + The shared libraries 'libgmp.so' and 'libmp.so' are not affected by + this and any version of 'strip' can be used on them. + +'make' syntax error + On certain versions of SCO OpenServer 5 and IRIX 6.5 the native + 'make' is unable to handle the long dependencies list for + 'libgmp.la'. The symptom is a "syntax error" on the following line + of the top-level 'Makefile'. + + libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES) + + Either use GNU Make, or as a workaround remove + '$(libgmp_la_DEPENDENCIES)' from that line (which will make the + initial build work, but if any recompiling is done 'libgmp.la' + might not be rebuilt). + +MacOS X ('*-*-darwin*') + Libtool currently only knows how to create shared libraries on + MacOS X using the native 'cc' (which is a modified GCC), not a + plain GCC. A static-only build should work though + ('--disable-shared'). + +NeXT prior to 3.3 + The system compiler on old versions of NeXT was a massacred and old + GCC, even if it called itself 'cc'. This compiler cannot be used + to build GMP, you need to get a real GCC, and install that. (NeXT + may have fixed this in release 3.3 of their system.) + +POWER and PowerPC + Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP + on POWER or PowerPC. If you want to use GCC for these machines, + get GCC 2.7.2.1 (or later). + +Sequent Symmetry + Use the GNU assembler instead of the system assembler, since the + latter has serious bugs. + +Solaris 2.6 + The system 'sed' prints an error "Output line too long" when + libtool builds 'libgmp.la'. This doesn't seem to cause any obvious + ill effects, but GNU 'sed' is recommended, to avoid any doubt. + +Sparc Solaris 2.7 with gcc 2.95.2 in 'ABI=32' + A shared library build of GMP seems to fail in this combination, it + builds but then fails the tests, apparently due to some incorrect + data relocations within 'gmp_randinit_lc_2exp_size'. The exact + cause is unknown, '--disable-shared' is recommended. + + +File: gmp.info, Node: Performance optimization, Prev: Known Build Problems, Up: Installing GMP + +2.6 Performance optimization +============================ + +For optimal performance, build GMP for the exact CPU type of the target +computer, see *note Build Options::. + + Unlike what is the case for most other programs, the compiler +typically doesn't matter much, since GMP uses assembly language for the +most critical operation. + + In particular for long-running GMP applications, and applications +demanding extremely large numbers, building and running the 'tuneup' +program in the 'tune' subdirectory can be important. For example, + + cd tune + make tuneup + ./tuneup + + will generate better contents for the 'gmp-mparam.h' parameter file. + + To use the results, put the output in the file indicated in the +'Parameters for ...' header. Then recompile from scratch. + + The 'tuneup' program takes one useful parameter, '-f NNN', which +instructs the program how long to check FFT multiply parameters. If +you're going to use GMP for extremely large numbers, you may want to run +'tuneup' with a large NNN value. + + +File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top + +3 GMP Basics +************ + +*Using functions, macros, data types, etc. not documented in this manual +is strongly discouraged. If you do so your application is guaranteed to +be incompatible with future versions of GMP.* + +* Menu: + +* Headers and Libraries:: +* Nomenclature and Types:: +* Function Classes:: +* Variable Conventions:: +* Parameter Conventions:: +* Memory Management:: +* Reentrancy:: +* Useful Macros and Constants:: +* Compatibility with older versions:: +* Demonstration Programs:: +* Efficiency:: +* Debugging:: +* Profiling:: +* Autoconf:: +* Emacs:: + + +File: gmp.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: GMP Basics, Up: GMP Basics + +3.1 Headers and Libraries +========================= + +All declarations needed to use GMP are collected in the include file +'gmp.h', except for the *note C++ Class Interface:: which comes with its +own separate header 'gmpxx.h'. 'gmp.h' is designed to work with both C +and C++ compilers. + + #include + + Note however that prototypes for GMP functions with 'FILE *' +parameters are only provided if '' is included before. + + #include + #include + + Likewise '' is required for prototypes with 'va_list' +parameters, such as 'gmp_vprintf'. And '' for prototypes +with 'struct obstack' parameters, such as 'gmp_obstack_printf', when +available. + + All programs using GMP must link against the 'libgmp' library. On a +typical Unix-like system this can be done with '-lgmp', for example + + gcc myprogram.c -lgmp + + GMP C++ functions are in a separate 'libgmpxx' library, including the +*note C++ Class Interface:: but also *note C++ Formatted Output:: for +regular GMP types. This is built and installed if C++ support has been +enabled (*note Build Options::). For example, + + g++ mycxxprog.cc -lgmpxx -lgmp + + GMP is built using Libtool and an application can use that to link if +desired, *note GNU Libtool: (libtool)Top. + + If GMP has been installed to a non-standard location then it may be +necessary to use '-I' and '-L' compiler options to point to the right +directories, and some sort of run-time path for a shared library. + + +File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: Headers and Libraries, Up: GMP Basics + +3.2 Nomenclature and Types +========================== + +In this manual, "integer" usually means a multiple precision integer, as +defined by the GMP library. The C data type for such integers is +'mpz_t'. Here are some examples of how to declare such integers: + + mpz_t sum; + + struct foo { mpz_t x, y; }; + + mpz_t vec[20]; + + "Rational number" means a multiple precision fraction. The C data +type for these fractions is 'mpq_t'. For example: + + mpq_t quotient; + + "Floating point number" or "Float" for short, is an arbitrary +precision mantissa with a limited precision exponent. The C data type +for such objects is 'mpf_t'. For example: + + mpf_t fp; + + The floating point functions accept and return exponents in the C +type 'mp_exp_t'. Currently this is usually a 'long', but on some +systems it's an 'int' for efficiency. + + A "limb" means the part of a multi-precision number that fits in a +single machine word. (We chose this word because a limb of the human +body is analogous to a digit, only larger, and containing several +digits.) Normally a limb is 32 or 64 bits. The C data type for a limb +is 'mp_limb_t'. + + Counts of limbs of a multi-precision number represented in the C type +'mp_size_t'. Currently this is normally a 'long', but on some systems +it's an 'int' for efficiency, and on some systems it will be 'long long' +in the future. + + Counts of bits of a multi-precision number are represented in the C +type 'mp_bitcnt_t'. Currently this is always an 'unsigned long', but on +some systems it will be an 'unsigned long long' in the future. + + "Random state" means an algorithm selection and current state data. +The C data type for such objects is 'gmp_randstate_t'. For example: + + gmp_randstate_t rstate; + + Also, in general 'mp_bitcnt_t' is used for bit counts and ranges, and +'size_t' is used for byte or character counts. + + + Internally, GMP data types such as 'mpz_t' are defined as one-element +arrays, whose element type is part of the GMP internals (*note +Internals::). + + When an array is used as a function argument in C, it is not passed +by value, instead its value is a pointer to the first element. In C +jargon, this is sometimes referred to as the array "decaying" to a +pointer. For GMP types like 'mpz_t', that means that the function +called gets a pointer to the caller's 'mpz_t' value, which is why no +explicit '&' operator is needed when passing output arguments (*note +Parameter Conventions::). + + GMP defines names for these pointer types, e.g., 'mpz_ptr' +corresponding to 'mpz_t', and 'mpz_srcptr' corresponding to 'const +mpz_t'. Most functions don't need to use these pointer types directly; +it works fine to declare a function using the 'mpz_t' or 'const mpz_t' +as the argument types, the same "pointer decay" happens in the +background regardless. + + Occasionally, it is useful to manipulate pointers directly, e.g., to +conditionally swap _references_ to a function's inputs without changing +the _values_ as seen by the caller, or returning a pointer to an 'mpz_t' +which is part of a larger structure. For these cases, the pointer types +are necessary. And a 'mpz_ptr' can be passed as argument to any GMP +function declared to take an 'mpz_t' argument. + + Their definition is equivalent to the following code, which is given +for illustratory purposes only: + + typedef foo_internal foo_t[1]; + typedef foo_internal * foo_ptr; + typedef const foo_internal * foo_srcptr; + + The following pointer types are defined by GMP: + * 'mpz_ptr' for pointers to the element type in 'mpz_t' + * 'mpz_srcptr' for 'const' pointers to the element type in 'mpz_t' + * 'mpq_ptr' for pointers to the element type in 'mpq_t' + * 'mpq_srcptr' for 'const' pointers to the element type in 'mpq_t' + * 'mpf_ptr' for pointers to the element type in 'mpf_t' + * 'mpf_srcptr' for 'const' pointers to the element type in 'mpf_t' + * 'gmp_randstate_ptr' for pointers to the element type in + 'gmp_randstate_t' + * 'gmp_randstate_srcptr' for 'const' pointers to the element type in + 'gmp_randstate_t' + + +File: gmp.info, Node: Function Classes, Next: Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics + +3.3 Function Classes +==================== + +There are six classes of functions in the GMP library: + + 1. Functions for signed integer arithmetic, with names beginning with + 'mpz_'. The associated type is 'mpz_t'. There are about 150 + functions in this class. (*note Integer Functions::) + + 2. Functions for rational number arithmetic, with names beginning with + 'mpq_'. The associated type is 'mpq_t'. There are about 35 + functions in this class, but the integer functions can be used for + arithmetic on the numerator and denominator separately. (*note + Rational Number Functions::) + + 3. Functions for floating-point arithmetic, with names beginning with + 'mpf_'. The associated type is 'mpf_t'. There are about 70 + functions in this class. (*note Floating-point Functions::) + + 4. Fast low-level functions that operate on natural numbers. These + are used by the functions in the preceding groups, and you can also + call them directly from very time-critical user programs. These + functions' names begin with 'mpn_'. The associated type is array + of 'mp_limb_t'. There are about 60 (hard-to-use) functions in this + class. (*note Low-level Functions::) + + 5. Miscellaneous functions. Functions for setting up custom + allocation and functions for generating random numbers. (*note + Custom Allocation::, and *note Random Number Functions::) + + +File: gmp.info, Node: Variable Conventions, Next: Parameter Conventions, Prev: Function Classes, Up: GMP Basics + +3.4 Variable Conventions +======================== + +GMP functions generally have output arguments before input arguments. +This notation is by analogy with the assignment operator. + + GMP lets you use the same variable for both input and output in one +call. For example, the main function for integer multiplication, +'mpz_mul', can be used to square 'x' and put the result back in 'x' with + + mpz_mul (x, x, x); + + Before you can assign to a GMP variable, you need to initialize it by +calling one of the special initialization functions. When you're done +with a variable, you need to clear it out, using one of the functions +for that purpose. Which function to use depends on the type of +variable. See the chapters on integer functions, rational number +functions, and floating-point functions for details. + + A variable should only be initialized once, or at least cleared +between each initialization. After a variable has been initialized, it +may be assigned to any number of times. + + For efficiency reasons, avoid excessive initializing and clearing. +In general, initialize near the start of a function and clear near the +end. For example, + + void + foo (void) + { + mpz_t n; + int i; + mpz_init (n); + for (i = 1; i < 100; i++) + { + mpz_mul (n, ...); + mpz_fdiv_q (n, ...); + ... + } + mpz_clear (n); + } + + GMP types like 'mpz_t' are implemented as one-element arrays of +certain structures. Declaring a variable creates an object with the +fields GMP needs, but variables are normally manipulated by using the +pointer to the object. The appropriate pointer types (*note +Nomenclature and Types::) may be used to explicitly manipulate the +pointer. For both behavior and efficiency reasons, it is discouraged to +make copies of the GMP object itself (either directly or via aggregate +objects containing such GMP objects). If copies are done, all of them +must be used read-only; using a copy as the output of some function will +invalidate all the other copies. Note that the actual fields in each +'mpz_t' etc are for internal use only and should not be accessed +directly by code that expects to be compatible with future GMP releases. + + +File: gmp.info, Node: Parameter Conventions, Next: Memory Management, Prev: Variable Conventions, Up: GMP Basics + +3.5 Parameter Conventions +========================= + +When a GMP variable is used as a function parameter, it's effectively a +call-by-reference, meaning that when the function stores a value there +it will change the original in the caller. Parameters which are +input-only can be designated 'const' to provoke a compiler error or +warning on attempting to modify them. + + When a function is going to return a GMP result, it should designate +a parameter that it sets, like the library functions do. More than one +value can be returned by having more than one output parameter, again +like the library functions. A 'return' of an 'mpz_t' etc doesn't return +the object, only a pointer, and this is almost certainly not what's +wanted. + + Here's an example accepting an 'mpz_t' parameter, doing a +calculation, and storing the result to the indicated parameter. + + void + foo (mpz_t result, const mpz_t param, unsigned long n) + { + unsigned long i; + mpz_mul_ui (result, param, n); + for (i = 1; i < n; i++) + mpz_add_ui (result, result, i*7); + } + + int + main (void) + { + mpz_t r, n; + mpz_init (r); + mpz_init_set_str (n, "123456", 0); + foo (r, n, 20L); + gmp_printf ("%Zd\n", r); + return 0; + } + + Our function 'foo' works even if its caller passes the same variable +for 'param' and 'result', just like the library functions. But +sometimes it's tricky to make that work, and an application might not +want to bother supporting that sort of thing. + + Since GMP types are implemented as one-element arrays, using a GMP +variable as a parameter passes a pointer to the object. Hence the +call-by-reference. A more explicit (and equivalent) prototype for our +function 'foo' could be: + + void foo (mpz_ptr result, mpz_srcptr param, unsigned long n); + + +File: gmp.info, Node: Memory Management, Next: Reentrancy, Prev: Parameter Conventions, Up: GMP Basics + +3.6 Memory Management +===================== + +The GMP types like 'mpz_t' are small, containing only a couple of sizes, +and pointers to allocated data. Once a variable is initialized, GMP +takes care of all space allocation. Additional space is allocated +whenever a variable doesn't have enough. + + 'mpz_t' and 'mpq_t' variables never reduce their allocated space. +Normally this is the best policy, since it avoids frequent reallocation. +Applications that need to return memory to the heap at some particular +point can use 'mpz_realloc2', or clear variables no longer needed. + + 'mpf_t' variables, in the current implementation, use a fixed amount +of space, determined by the chosen precision and allocated at +initialization, so their size doesn't change. + + All memory is allocated using 'malloc' and friends by default, but +this can be changed, see *note Custom Allocation::. Temporary memory on +the stack is also used (via 'alloca'), but this can be changed at +build-time if desired, see *note Build Options::. + + +File: gmp.info, Node: Reentrancy, Next: Useful Macros and Constants, Prev: Memory Management, Up: GMP Basics + +3.7 Reentrancy +============== + +GMP is reentrant and thread-safe, with some exceptions: + + * If configured with '--enable-alloca=malloc-notreentrant' (or with + '--enable-alloca=notreentrant' when 'alloca' is not available), + then naturally GMP is not reentrant. + + * 'mpf_set_default_prec' and 'mpf_init' use a global variable for the + selected precision. 'mpf_init2' can be used instead, and in the + C++ interface an explicit precision to the 'mpf_class' constructor. + + * 'mpz_random' and the other old random number functions use a global + random state and are hence not reentrant. The newer random number + functions that accept a 'gmp_randstate_t' parameter can be used + instead. + + * 'gmp_randinit' (obsolete) returns an error indication through a + global variable, which is not thread safe. Applications are + advised to use 'gmp_randinit_default' or 'gmp_randinit_lc_2exp' + instead. + + * 'mp_set_memory_functions' uses global variables to store the + selected memory allocation functions. + + * If the memory allocation functions set by a call to + 'mp_set_memory_functions' (or 'malloc' and friends by default) are + not reentrant, then GMP will not be reentrant either. + + * If the standard I/O functions such as 'fwrite' are not reentrant + then the GMP I/O functions using them will not be reentrant either. + + * It's safe for two threads to read from the same GMP variable + simultaneously, but it's not safe for one to read while another + might be writing, nor for two threads to write simultaneously. + It's not safe for two threads to generate a random number from the + same 'gmp_randstate_t' simultaneously, since this involves an + update of that variable. + + +File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: Reentrancy, Up: GMP Basics + +3.8 Useful Macros and Constants +=============================== + + -- Global Constant: const int mp_bits_per_limb + The number of bits per limb. + + -- Macro: __GNU_MP_VERSION + -- Macro: __GNU_MP_VERSION_MINOR + -- Macro: __GNU_MP_VERSION_PATCHLEVEL + The major and minor GMP version, and patch level, respectively, as + integers. For GMP i.j, these numbers will be i, j, and 0, + respectively. For GMP i.j.k, these numbers will be i, j, and k, + respectively. + + -- Global Constant: const char * const gmp_version + The GMP version number, as a null-terminated string, in the form + "i.j.k". This release is "6.3.0". Note that the format "i.j" was + used, before version 4.3.0, when k was zero. + + -- Macro: __GMP_CC + -- Macro: __GMP_CFLAGS + The compiler and compiler flags, respectively, used when compiling + GMP, as strings. + + +File: gmp.info, Node: Compatibility with older versions, Next: Demonstration Programs, Prev: Useful Macros and Constants, Up: GMP Basics + +3.9 Compatibility with older versions +===================================== + +This version of GMP is upwardly binary compatible with all 5.x, 4.x, and +3.x versions, and upwardly compatible at the source level with all 2.x +versions, with the following exceptions. + + * 'mpn_gcd' had its source arguments swapped as of GMP 3.0, for + consistency with other 'mpn' functions. + + * 'mpf_get_prec' counted precision slightly differently in GMP 3.0 + and 3.0.1, but in 3.1 reverted to the 2.x style. + + * 'mpn_bdivmod', documented as preliminary in GMP 4, has been + removed. + + There are a number of compatibility issues between GMP 1 and GMP 2 +that of course also apply when porting applications from GMP 1 to GMP 5. +Please see the GMP 2 manual for details. + + +File: gmp.info, Node: Demonstration Programs, Next: Efficiency, Prev: Compatibility with older versions, Up: GMP Basics + +3.10 Demonstration programs +=========================== + +The 'demos' subdirectory has some sample programs using GMP. These +aren't built or installed, but there's a 'Makefile' with rules for them. +For instance, + + make pexpr + ./pexpr 68^975+10 + +The following programs are provided + + * 'pexpr' is an expression evaluator, the program used on the GMP web + page. + * The 'calc' subdirectory has a similar but simpler evaluator using + 'lex' and 'yacc'. + * The 'expr' subdirectory is yet another expression evaluator, a + library designed for ease of use within a C program. See + 'demos/expr/README' for more information. + * 'factorize' is a Pollard-Rho factorization program. + * 'isprime' is a command-line interface to the 'mpz_probab_prime_p' + function. + * 'primes' counts or lists primes in an interval, using a sieve. + * 'qcn' is an example use of 'mpz_kronecker_ui' to estimate quadratic + class numbers. + * The 'perl' subdirectory is a comprehensive perl interface to GMP. + See 'demos/perl/INSTALL' for more information. Documentation is in + POD format in 'demos/perl/GMP.pm'. + + As an aside, consideration has been given at various times to some +sort of expression evaluation within the main GMP library. Going beyond +something minimal quickly leads to matters like user-defined functions, +looping, fixnums for control variables, etc, which are considered +outside the scope of GMP (much closer to language interpreters or +compilers, *Note Language Bindings::). Something simple for program +input convenience may yet be a possibility, a combination of the 'expr' +demo and the 'pexpr' tree back-end perhaps. But for now the above +evaluators are offered as illustrations. + + +File: gmp.info, Node: Efficiency, Next: Debugging, Prev: Demonstration Programs, Up: GMP Basics + +3.11 Efficiency +=============== + +Small Operands + On small operands, the time for function call overheads and memory + allocation can be significant in comparison to actual calculation. + This is unavoidable in a general purpose variable precision + library, although GMP attempts to be as efficient as it can on both + large and small operands. + +Static Linking + On some CPUs, in particular the x86s, the static 'libgmp.a' should + be used for maximum speed, since the PIC code in the shared + 'libgmp.so' will have a small overhead on each function call and + global data address. For many programs this will be insignificant, + but for long calculations there's a gain to be had. + +Initializing and Clearing + Avoid excessive initializing and clearing of variables, since this + can be quite time consuming, especially in comparison to otherwise + fast operations like addition. + + A language interpreter might want to keep a free list or stack of + initialized variables ready for use. It should be possible to + integrate something like that with a garbage collector too. + +Reallocations + An 'mpz_t' or 'mpq_t' variable used to hold successively increasing + values will have its memory repeatedly 'realloc'ed, which could be + quite slow or could fragment memory, depending on the C library. + If an application can estimate the final size then 'mpz_init2' or + 'mpz_realloc2' can be called to allocate the necessary space from + the beginning (*note Initializing Integers::). + + It doesn't matter if a size set with 'mpz_init2' or 'mpz_realloc2' + is too small, since all functions will do a further reallocation if + necessary. Badly overestimating memory required will waste space + though. + +'2exp' Functions + It's up to an application to call functions like 'mpz_mul_2exp' + when appropriate. General purpose functions like 'mpz_mul' make no + attempt to identify powers of two or other special forms, because + such inputs will usually be very rare and testing every time would + be wasteful. + +'ui' and 'si' Functions + The 'ui' functions and the small number of 'si' functions exist for + convenience and should be used where applicable. But if for + example an 'mpz_t' contains a value that fits in an 'unsigned long' + there's no need to extract it and call a 'ui' function, just use + the regular 'mpz' function. + +In-Place Operations + 'mpz_abs', 'mpq_abs', 'mpf_abs', 'mpz_neg', 'mpq_neg' and 'mpf_neg' + are fast when used for in-place operations like 'mpz_abs(x,x)', + since in the current implementation only a single field of 'x' + needs changing. On suitable compilers (GCC for instance) this is + inlined too. + + 'mpz_add_ui', 'mpz_sub_ui', 'mpf_add_ui' and 'mpf_sub_ui' benefit + from an in-place operation like 'mpz_add_ui(x,x,y)', since usually + only one or two limbs of 'x' will need to be changed. The same + applies to the full precision 'mpz_add' etc if 'y' is small. If + 'y' is big then cache locality may be helped, but that's all. + + 'mpz_mul' is currently the opposite, a separate destination is + slightly better. A call like 'mpz_mul(x,x,y)' will, unless 'y' is + only one limb, make a temporary copy of 'x' before forming the + result. Normally that copying will only be a tiny fraction of the + time for the multiply, so this is not a particularly important + consideration. + + 'mpz_set', 'mpq_set', 'mpq_set_num', 'mpf_set', etc, make no + attempt to recognise a copy of something to itself, so a call like + 'mpz_set(x,x)' will be wasteful. Naturally that would never be + written deliberately, but if it might arise from two pointers to + the same object then a test to avoid it might be desirable. + + if (x != y) + mpz_set (x, y); + + Note that it's never worth introducing extra 'mpz_set' calls just + to get in-place operations. If a result should go to a particular + variable then just direct it there and let GMP take care of data + movement. + +Divisibility Testing (Small Integers) + 'mpz_divisible_ui_p' and 'mpz_congruent_ui_p' are the best + functions for testing whether an 'mpz_t' is divisible by an + individual small integer. They use an algorithm which is faster + than 'mpz_tdiv_ui', but which gives no useful information about the + actual remainder, only whether it's zero (or a particular value). + + However when testing divisibility by several small integers, it's + best to take a remainder modulo their product, to save + multi-precision operations. For instance to test whether a number + is divisible by 23, 29 or 31 take a remainder modulo 23*29*31 = + 20677 and then test that. + + The division functions like 'mpz_tdiv_q_ui' which give a quotient + as well as a remainder are generally a little slower than the + remainder-only functions like 'mpz_tdiv_ui'. If the quotient is + only rarely wanted then it's probably best to just take a remainder + and then go back and calculate the quotient if and when it's wanted + ('mpz_divexact_ui' can be used if the remainder is zero). + +Rational Arithmetic + The 'mpq' functions operate on 'mpq_t' values with no common + factors in the numerator and denominator. Common factors are + checked-for and cast out as necessary. In general, cancelling + factors every time is the best approach since it minimizes the + sizes for subsequent operations. + + However, applications that know something about the factorization + of the values they're working with might be able to avoid some of + the GCDs used for canonicalization, or swap them for divisions. + For example when multiplying by a prime it's enough to check for + factors of it in the denominator instead of doing a full GCD. Or + when forming a big product it might be known that very little + cancellation will be possible, and so canonicalization can be left + to the end. + + The 'mpq_numref' and 'mpq_denref' macros give access to the + numerator and denominator to do things outside the scope of the + supplied 'mpq' functions. *Note Applying Integer Functions::. + + The canonical form for rationals allows mixed-type 'mpq_t' and + integer additions or subtractions to be done directly with + multiples of the denominator. This will be somewhat faster than + 'mpq_add'. For example, + + /* mpq increment */ + mpz_add (mpq_numref(q), mpq_numref(q), mpq_denref(q)); + + /* mpq += unsigned long */ + mpz_addmul_ui (mpq_numref(q), mpq_denref(q), 123UL); + + /* mpq -= mpz */ + mpz_submul (mpq_numref(q), mpq_denref(q), z); + +Number Sequences + Functions like 'mpz_fac_ui', 'mpz_fib_ui' and 'mpz_bin_uiui' are + designed for calculating isolated values. If a range of values is + wanted it's probably best to get a starting point and iterate from + there. + +Text Input/Output + Hexadecimal or octal are suggested for input or output in text + form. Power-of-2 bases like these can be converted much more + efficiently than other bases, like decimal. For big numbers + there's usually nothing of particular interest to be seen in the + digits, so the base doesn't matter much. + + Maybe we can hope octal will one day become the normal base for + everyday use, as proposed by King Charles XII of Sweden and later + reformers. + + +File: gmp.info, Node: Debugging, Next: Profiling, Prev: Efficiency, Up: GMP Basics + +3.12 Debugging +============== + +Stack Overflow + Depending on the system, a segmentation violation or bus error + might be the only indication of stack overflow. See + '--enable-alloca' choices in *note Build Options::, for how to + address this. + + In new enough versions of GCC, '-fstack-check' may be able to + ensure an overflow is recognised by the system before too much + damage is done, or '-fstack-limit-symbol' or + '-fstack-limit-register' may be able to add checking if the system + itself doesn't do any (*note Options for Code Generation: (gcc)Code + Gen Options.). These options must be added to the 'CFLAGS' used in + the GMP build (*note Build Options::), adding them just to an + application will have no effect. Note also they're a slowdown, + adding overhead to each function call and each stack allocation. + +Heap Problems + The most likely cause of application problems with GMP is heap + corruption. Failing to 'init' GMP variables will have + unpredictable effects, and corruption arising elsewhere in a + program may well affect GMP. Initializing GMP variables more than + once or failing to clear them will cause memory leaks. + + In all such cases a 'malloc' debugger is recommended. On a GNU or + BSD system the standard C library 'malloc' has some diagnostic + facilities, see *note Allocation Debugging: (libc)Allocation + Debugging, or 'man 3 malloc'. Other possibilities, in no + particular order, include + + + + + + The GMP default allocation routines in 'memory.c' also have a + simple sentinel scheme which can be enabled with '#define DEBUG' in + that file. This is mainly designed for detecting buffer overruns + during GMP development, but might find other uses. + +Stack Backtraces + On some systems the compiler options GMP uses by default can + interfere with debugging. In particular on x86 and 68k systems + '-fomit-frame-pointer' is used and this generally inhibits stack + backtracing. Recompiling without such options may help while + debugging, though the usual caveats about it potentially moving a + memory problem or hiding a compiler bug will apply. + +GDB, the GNU Debugger + A sample '.gdbinit' is included in the distribution, showing how to + call some undocumented dump functions to print GMP variables from + within GDB. Note that these functions shouldn't be used in final + application code since they're undocumented and may be subject to + incompatible changes in future versions of GMP. + +Source File Paths + GMP has multiple source files with the same name, in different + directories. For example 'mpz', 'mpq' and 'mpf' each have an + 'init.c'. If the debugger can't already determine the right one it + may help to build with absolute paths on each C file. One way to + do that is to use a separate object directory with an absolute path + to the source directory. + + cd /my/build/dir + /my/source/dir/gmp-6.3.0/configure + + This works via 'VPATH', and might require GNU 'make'. Alternately + it might be possible to change the '.c.lo' rules appropriately. + +Assertion Checking + The build option '--enable-assert' is available to add some + consistency checks to the library (see *note Build Options::). + These are likely to be of limited value to most applications. + Assertion failures are just as likely to indicate memory corruption + as a library or compiler bug. + + Applications using the low-level 'mpn' functions, however, will + benefit from '--enable-assert' since it adds checks on the + parameters of most such functions, many of which have subtle + restrictions on their usage. Note however that only the generic C + code has checks, not the assembly code, so '--disable-assembly' + should be used for maximum checking. + +Temporary Memory Checking + The build option '--enable-alloca=debug' arranges that each block + of temporary memory in GMP is allocated with a separate call to + 'malloc' (or the allocation function set with + 'mp_set_memory_functions'). + + This can help a malloc debugger detect accesses outside the + intended bounds, or detect memory not released. In a normal build, + on the other hand, temporary memory is allocated in blocks which + GMP divides up for its own use, or may be allocated with a compiler + builtin 'alloca' which will go nowhere near any malloc debugger + hooks. + +Maximum Debuggability + To summarize the above, a GMP build for maximum debuggability would + be + + ./configure --disable-shared --enable-assert \ + --enable-alloca=debug --disable-assembly CFLAGS=-g + + For C++, add '--enable-cxx CXXFLAGS=-g'. + +Checker + The GCC checker () + can be used with GMP. It contains a stub library which means GMP + applications compiled with checker can use a normal GMP build. + + A build of GMP with checking within GMP itself can be made. This + will run very very slowly. On GNU/Linux for example, + + ./configure --disable-assembly CC=checkergcc + + '--disable-assembly' must be used, since the GMP assembly code + doesn't support the checking scheme. The GMP C++ features cannot + be used, since current versions of checker (0.9.9.1) don't yet + support the standard C++ library. + +Valgrind + Valgrind () is a memory checker for x86, ARM, + MIPS, PowerPC, and S/390. It translates and emulates machine + instructions to do strong checks for uninitialized data (at the + level of individual bits), memory accesses through bad pointers, + and memory leaks. + + Valgrind does not always support every possible instruction, in + particular ones recently added to an ISA. Valgrind might therefore + be incompatible with a recent GMP or even a less recent GMP which + is compiled using a recent GCC. + + GMP's assembly code sometimes promotes a read of the limbs to some + larger size, for efficiency. GMP will do this even at the start + and end of a multilimb operand, using naturally aligned operations + on the larger type. This may lead to benign reads outside of + allocated areas, triggering complaints from Valgrind. Valgrind's + option '--partial-loads-ok=yes' should help. + +Other Problems + Any suspected bug in GMP itself should be isolated to make sure + it's not an application problem, see *note Reporting Bugs::. + + +File: gmp.info, Node: Profiling, Next: Autoconf, Prev: Debugging, Up: GMP Basics + +3.13 Profiling +============== + +Running a program under a profiler is a good way to find where it's +spending most time and where improvements can be best sought. The +profiling choices for a GMP build are as follows. + +'--disable-profiling' + The default is to add nothing special for profiling. + + It should be possible to just compile the mainline of a program + with '-p' and use 'prof' to get a profile consisting of timer-based + sampling of the program counter. Most of the GMP assembly code has + the necessary symbol information. + + This approach has the advantage of minimizing interference with + normal program operation, but on most systems the resolution of the + sampling is quite low (10 milliseconds for instance), requiring + long runs to get accurate information. + +'--enable-profiling=prof' + Build with support for the system 'prof', which means '-p' added to + the 'CFLAGS'. + + This provides call counting in addition to program counter + sampling, which allows the most frequently called routines to be + identified, and an average time spent in each routine to be + determined. + + The x86 assembly code has support for this option, but on other + processors the assembly routines will be as if compiled without + '-p' and therefore won't appear in the call counts. + + On some systems, such as GNU/Linux, '-p' in fact means '-pg' and in + this case '--enable-profiling=gprof' described below should be used + instead. + +'--enable-profiling=gprof' + Build with support for 'gprof', which means '-pg' added to the + 'CFLAGS'. + + This provides call graph construction in addition to call counting + and program counter sampling, which makes it possible to count + calls coming from different locations. For example the number of + calls to 'mpn_mul' from 'mpz_mul' versus the number from 'mpf_mul'. + The program counter sampling is still flat though, so only a total + time in 'mpn_mul' would be accumulated, not a separate amount for + each call site. + + The x86 assembly code has support for this option, but on other + processors the assembly routines will be as if compiled without + '-pg' and therefore not be included in the call counts. + + On x86 and m68k systems '-pg' and '-fomit-frame-pointer' are + incompatible, so the latter is omitted from the default flags in + that case, which might result in poorer code generation. + + Incidentally, it should be possible to use the 'gprof' program with + a plain '--enable-profiling=prof' build. But in that case only the + 'gprof -p' flat profile and call counts can be expected to be + valid, not the 'gprof -q' call graph. + +'--enable-profiling=instrument' + Build with the GCC option '-finstrument-functions' added to the + 'CFLAGS' (*note Options for Code Generation: (gcc)Code Gen + Options.). + + This inserts special instrumenting calls at the start and end of + each function, allowing exact timing and full call graph + construction. + + This instrumenting is not normally a standard system feature and + will require support from an external library, such as + + + + This should be included in 'LIBS' during the GMP configure so that + test programs will link. For example, + + ./configure --enable-profiling=instrument LIBS=-lfc + + On a GNU system the C library provides dummy instrumenting + functions, so programs compiled with this option will link. In + this case it's only necessary to ensure the correct library is + added when linking an application. + + The x86 assembly code supports this option, but on other processors + the assembly routines will be as if compiled without + '-finstrument-functions' meaning time spent in them will + effectively be attributed to their caller. + + +File: gmp.info, Node: Autoconf, Next: Emacs, Prev: Profiling, Up: GMP Basics + +3.14 Autoconf +============= + +Autoconf based applications can easily check whether GMP is installed. +The only thing to be noted is that GMP library symbols from version 3 +onwards have prefixes like '__gmpz'. The following therefore would be a +simple test, + + AC_CHECK_LIB(gmp, __gmpz_init) + + This just uses the default 'AC_CHECK_LIB' actions for found or not +found, but an application that must have GMP would want to generate an +error if not found. For example, + + AC_CHECK_LIB(gmp, __gmpz_init, , + [AC_MSG_ERROR([GNU MP not found, see https://gmplib.org/])]) + + If functions added in some particular version of GMP are required, +then one of those can be used when checking. For example 'mpz_mul_si' +was added in GMP 3.1, + + AC_CHECK_LIB(gmp, __gmpz_mul_si, , + [AC_MSG_ERROR( + [GNU MP not found, or not 3.1 or up, see https://gmplib.org/])]) + + An alternative would be to test the version number in 'gmp.h' using +say 'AC_EGREP_CPP'. That would make it possible to test the exact +version, if some particular sub-minor release is known to be necessary. + + In general it's recommended that applications should simply demand a +new enough GMP rather than trying to provide supplements for features +not available in past versions. + + Occasionally an application will need or want to know the size of a +type at configuration or preprocessing time, not just with 'sizeof' in +the code. This can be done in the normal way with 'mp_limb_t' etc, but +GMP 4.0 or up is best for this, since prior versions needed certain '-D' +defines on systems using a 'long long' limb. The following would suit +Autoconf 2.50 or up, + + AC_CHECK_SIZEOF(mp_limb_t, , [#include ]) + + +File: gmp.info, Node: Emacs, Prev: Autoconf, Up: GMP Basics + +3.15 Emacs +========== + + ('info-lookup-symbol') is a good way to find documentation on +C functions while editing (*note Info Documentation Lookup: (emacs)Info +Lookup.). + + The GMP manual can be included in such lookups by putting the +following in your '.emacs', + + (eval-after-load "info-look" + '(let ((mode-value (assoc 'c-mode (assoc 'symbol info-lookup-alist)))) + (setcar (nthcdr 3 mode-value) + (cons '("(gmp)Function Index" nil "^ -.* " "\\>") + (nth 3 mode-value))))) + + +File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top + +4 Reporting Bugs +**************** + +If you think you have found a bug in the GMP library, please investigate +it and report it. We have made this library available to you, and it is +not too much to ask you to report the bugs you find. + + Before you report a bug, check it's not already addressed in *note +Known Build Problems::, or perhaps *note Notes for Particular Systems::. +You may also want to check for patches for this +release, or try a recent snapshot from +. + + Please include the following in any report: + + * The GMP version number, and if pre-packaged or patched then say so. + + * A test program that makes it possible for us to reproduce the bug. + Include instructions on how to run the program. + + * A description of what is wrong. If the results are incorrect, in + what way. If you get a crash, say so. + + * If you get a crash, include a stack backtrace from the debugger if + it's informative ('where' in 'gdb', or '$C' in 'adb'). + + * Please do not send core dumps, executables or 'strace's. + + * The 'configure' options you used when building GMP, if any. + + * The output from 'configure', as printed to stdout, with any options + used. + + * The name of the compiler and its version. For 'gcc', get the + version with 'gcc -v', otherwise perhaps 'what `which cc`', or + similar. + + * The output from running 'uname -a'. + + * The output from running './config.guess', and from running + './configfsf.guess' (might be the same). + + * If the bug is related to 'configure', then the compressed contents + of 'config.log'. + + * If the bug is related to an 'asm' file not assembling, then the + contents of 'config.m4' and the offending line or lines from the + temporary 'mpn/tmp-.s'. + + Please make an effort to produce a self-contained report, with +something definite that can be tested or debugged. Vague queries or +piecemeal messages are difficult to act on and don't help the +development effort. + + It is not uncommon that an observed problem is actually due to a bug +in the compiler; the GMP code tends to explore interesting corners in +compilers. + + If your bug report is good, we will do our best to help you get a +corrected version of the library; if the bug report is poor, we won't do +anything about it (except maybe ask you to send a better report). + + Send your report to: . + + If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please send a note +to the same address. + + +File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top + +5 Integer Functions +******************* + +This chapter describes the GMP functions for performing integer +arithmetic. These functions start with the prefix 'mpz_'. + + GMP integers are stored in objects of type 'mpz_t'. + +* Menu: + +* Initializing Integers:: +* Assigning Integers:: +* Simultaneous Integer Init & Assign:: +* Converting Integers:: +* Integer Arithmetic:: +* Integer Division:: +* Integer Exponentiation:: +* Integer Roots:: +* Number Theoretic Functions:: +* Integer Comparisons:: +* Integer Logic and Bit Fiddling:: +* I/O of Integers:: +* Integer Random Numbers:: +* Integer Import and Export:: +* Miscellaneous Integer Functions:: +* Integer Special Functions:: + + +File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Prev: Integer Functions, Up: Integer Functions + +5.1 Initialization Functions +============================ + +The functions for integer arithmetic assume that all integer objects are +initialized. You do that by calling the function 'mpz_init'. For +example, + + { + mpz_t integ; + mpz_init (integ); + ... + mpz_add (integ, ...); + ... + mpz_sub (integ, ...); + + /* Unless the program is about to exit, do ... */ + mpz_clear (integ); + } + + As you can see, you can store new values any number of times, once an +object is initialized. + + -- Function: void mpz_init (mpz_t X) + Initialize X, and set its value to 0. + + -- Function: void mpz_inits (mpz_t X, ...) + Initialize a NULL-terminated list of 'mpz_t' variables, and set + their values to 0. + + -- Function: void mpz_init2 (mpz_t X, mp_bitcnt_t N) + Initialize X, with space for N-bit numbers, and set its value to 0. + Calling this function instead of 'mpz_init' or 'mpz_inits' is never + necessary; reallocation is handled automatically by GMP when + needed. + + While N defines the initial space, X will grow automatically in the + normal way, if necessary, for subsequent values stored. + 'mpz_init2' makes it possible to avoid such reallocations if a + maximum size is known in advance. + + In preparation for an operation, GMP often allocates one limb more + than ultimately needed. To make sure GMP will not perform + reallocation for X, you need to add the number of bits in + 'mp_limb_t' to N. + + -- Function: void mpz_clear (mpz_t X) + Free the space occupied by X. Call this function for all 'mpz_t' + variables when you are done with them. + + -- Function: void mpz_clears (mpz_t X, ...) + Free the space occupied by a NULL-terminated list of 'mpz_t' + variables. + + -- Function: void mpz_realloc2 (mpz_t X, mp_bitcnt_t N) + Change the space allocated for X to N bits. The value in X is + preserved if it fits, or is set to 0 if not. + + Calling this function is never necessary; reallocation is handled + automatically by GMP when needed. But this function can be used to + increase the space for a variable in order to avoid repeated + automatic reallocations, or to decrease it to give memory back to + the heap. + + +File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions + +5.2 Assignment Functions +======================== + +These functions assign new values to already initialized integers (*note +Initializing Integers::). + + -- Function: void mpz_set (mpz_t ROP, const mpz_t OP) + -- Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP) + -- Function: void mpz_set_si (mpz_t ROP, signed long int OP) + -- Function: void mpz_set_d (mpz_t ROP, double OP) + -- Function: void mpz_set_q (mpz_t ROP, const mpq_t OP) + -- Function: void mpz_set_f (mpz_t ROP, const mpf_t OP) + Set the value of ROP from OP. + + 'mpz_set_d', 'mpz_set_q' and 'mpz_set_f' truncate OP to make it an + integer. + + -- Function: int mpz_set_str (mpz_t ROP, const char *STR, int BASE) + Set the value of ROP from STR, a null-terminated C string in base + BASE. White space is allowed in the string, and is simply ignored. + + The BASE may vary from 2 to 62, or if BASE is 0, then the leading + characters are used: '0x' and '0X' for hexadecimal, '0b' and '0B' + for binary, '0' for octal, or decimal otherwise. + + For bases up to 36, case is ignored; upper-case and lower-case + letters have the same value. For bases 37 to 62, upper-case + letters represent the usual 10..35 while lower-case letters + represent 36..61. + + This function returns 0 if the entire string is a valid number in + base BASE. Otherwise it returns -1. + + -- Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2) + Swap the values ROP1 and ROP2 efficiently. + + +File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions + +5.3 Combined Initialization and Assignment Functions +==================================================== + +For convenience, GMP provides a parallel series of initialize-and-set +functions which initialize the output and then store the value there. +These functions' names have the form 'mpz_init_set...' + + Here is an example of using one: + + { + mpz_t pie; + mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); + ... + mpz_sub (pie, ...); + ... + mpz_clear (pie); + } + +Once the integer has been initialized by any of the 'mpz_init_set...' +functions, it can be used as the source or destination operand for the +ordinary integer functions. Don't use an initialize-and-set function on +a variable already initialized! + + -- Function: void mpz_init_set (mpz_t ROP, const mpz_t OP) + -- Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP) + -- Function: void mpz_init_set_si (mpz_t ROP, signed long int OP) + -- Function: void mpz_init_set_d (mpz_t ROP, double OP) + Initialize ROP with limb space and set the initial numeric value + from OP. + + -- Function: int mpz_init_set_str (mpz_t ROP, const char *STR, int + BASE) + Initialize ROP and set its value like 'mpz_set_str' (see its + documentation above for details). + + If the string is a correct base BASE number, the function returns + 0; if an error occurs it returns -1. ROP is initialized even if an + error occurs. (I.e., you have to call 'mpz_clear' for it.) + + +File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions + +5.4 Conversion Functions +======================== + +This section describes functions for converting GMP integers to standard +C types. Functions for converting _to_ GMP integers are described in +*note Assigning Integers:: and *note I/O of Integers::. + + -- Function: unsigned long int mpz_get_ui (const mpz_t OP) + Return the value of OP as an 'unsigned long'. + + If OP is too big to fit an 'unsigned long' then just the least + significant bits that do fit are returned. The sign of OP is + ignored, only the absolute value is used. + + -- Function: signed long int mpz_get_si (const mpz_t OP) + If OP fits into a 'signed long int' return the value of OP. + Otherwise return the least significant part of OP, with the same + sign as OP. + + If OP is too big to fit in a 'signed long int', the returned result + is probably not very useful. To find out if the value will fit, + use the function 'mpz_fits_slong_p'. + + -- Function: double mpz_get_d (const mpz_t OP) + Convert OP to a 'double', truncating if necessary (i.e. rounding + towards zero). + + If the exponent from the conversion is too big, the result is + system dependent. An infinity is returned where available. A + hardware overflow trap may or may not occur. + + -- Function: double mpz_get_d_2exp (signed long int *EXP, const mpz_t + OP) + Convert OP to a 'double', truncating if necessary (i.e. rounding + towards zero), and returning the exponent separately. + + The return value is in the range 0.5<=abs(D)<1 and the exponent is + stored to '*EXP'. D * 2^EXP is the (truncated) OP value. If OP is + zero, the return is 0.0 and 0 is stored to '*EXP'. + + This is similar to the standard C 'frexp' function (*note + (libc)Normalization Functions::). + + -- Function: char * mpz_get_str (char *STR, int BASE, const mpz_t OP) + Convert OP to a string of digits in base BASE. The base argument + may vary from 2 to 62 or from -2 to -36. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + If STR is 'NULL', the result string is allocated using the current + allocation function (*note Custom Allocation::). The block will be + 'strlen(str)+1' bytes, that being exactly enough for the string and + null-terminator. + + If STR is not 'NULL', it should point to a block of storage large + enough for the result, that being 'mpz_sizeinbase (OP, BASE) + 2'. + The two extra bytes are for a possible minus sign, and the + null-terminator. + + A pointer to the result string is returned, being either the + allocated block, or the given STR. + + +File: gmp.info, Node: Integer Arithmetic, Next: Integer Division, Prev: Converting Integers, Up: Integer Functions + +5.5 Arithmetic Functions +======================== + + -- Function: void mpz_add (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + -- Function: void mpz_add_ui (mpz_t ROP, const mpz_t OP1, unsigned long + int OP2) + Set ROP to OP1 + OP2. + + -- Function: void mpz_sub (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + -- Function: void mpz_sub_ui (mpz_t ROP, const mpz_t OP1, unsigned long + int OP2) + -- Function: void mpz_ui_sub (mpz_t ROP, unsigned long int OP1, const + mpz_t OP2) + Set ROP to OP1 - OP2. + + -- Function: void mpz_mul (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + -- Function: void mpz_mul_si (mpz_t ROP, const mpz_t OP1, long int OP2) + -- Function: void mpz_mul_ui (mpz_t ROP, const mpz_t OP1, unsigned long + int OP2) + Set ROP to OP1 times OP2. + + -- Function: void mpz_addmul (mpz_t ROP, const mpz_t OP1, const mpz_t + OP2) + -- Function: void mpz_addmul_ui (mpz_t ROP, const mpz_t OP1, unsigned + long int OP2) + Set ROP to ROP + OP1 times OP2. + + -- Function: void mpz_submul (mpz_t ROP, const mpz_t OP1, const mpz_t + OP2) + -- Function: void mpz_submul_ui (mpz_t ROP, const mpz_t OP1, unsigned + long int OP2) + Set ROP to ROP - OP1 times OP2. + + -- Function: void mpz_mul_2exp (mpz_t ROP, const mpz_t OP1, mp_bitcnt_t + OP2) + Set ROP to OP1 times 2 raised to OP2. This operation can also be + defined as a left shift by OP2 bits. + + -- Function: void mpz_neg (mpz_t ROP, const mpz_t OP) + Set ROP to -OP. + + -- Function: void mpz_abs (mpz_t ROP, const mpz_t OP) + Set ROP to the absolute value of OP. + + +File: gmp.info, Node: Integer Division, Next: Integer Exponentiation, Prev: Integer Arithmetic, Up: Integer Functions + +5.6 Division Functions +====================== + +Division is undefined if the divisor is zero. Passing a zero divisor to +the division or modulo functions (including the modular powering +functions 'mpz_powm' and 'mpz_powm_ui') will cause an intentional +division by zero. This lets a program handle arithmetic exceptions in +these functions the same way as for normal C 'int' arithmetic. + + -- Function: void mpz_cdiv_q (mpz_t Q, const mpz_t N, const mpz_t D) + -- Function: void mpz_cdiv_r (mpz_t R, const mpz_t N, const mpz_t D) + -- Function: void mpz_cdiv_qr (mpz_t Q, mpz_t R, const mpz_t N, const + mpz_t D) + + -- Function: unsigned long int mpz_cdiv_q_ui (mpz_t Q, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_cdiv_r_ui (mpz_t R, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_cdiv_qr_ui (mpz_t Q, mpz_t R, + const mpz_t N, unsigned long int D) + -- Function: unsigned long int mpz_cdiv_ui (const mpz_t N, + unsigned long int D) + + -- Function: void mpz_cdiv_q_2exp (mpz_t Q, const mpz_t N, + mp_bitcnt_t B) + -- Function: void mpz_cdiv_r_2exp (mpz_t R, const mpz_t N, + mp_bitcnt_t B) + + -- Function: void mpz_fdiv_q (mpz_t Q, const mpz_t N, const mpz_t D) + -- Function: void mpz_fdiv_r (mpz_t R, const mpz_t N, const mpz_t D) + -- Function: void mpz_fdiv_qr (mpz_t Q, mpz_t R, const mpz_t N, const + mpz_t D) + + -- Function: unsigned long int mpz_fdiv_q_ui (mpz_t Q, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_fdiv_r_ui (mpz_t R, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_fdiv_qr_ui (mpz_t Q, mpz_t R, + const mpz_t N, unsigned long int D) + -- Function: unsigned long int mpz_fdiv_ui (const mpz_t N, + unsigned long int D) + + -- Function: void mpz_fdiv_q_2exp (mpz_t Q, const mpz_t N, + mp_bitcnt_t B) + -- Function: void mpz_fdiv_r_2exp (mpz_t R, const mpz_t N, + mp_bitcnt_t B) + + -- Function: void mpz_tdiv_q (mpz_t Q, const mpz_t N, const mpz_t D) + -- Function: void mpz_tdiv_r (mpz_t R, const mpz_t N, const mpz_t D) + -- Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, const mpz_t N, const + mpz_t D) + + -- Function: unsigned long int mpz_tdiv_q_ui (mpz_t Q, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_tdiv_r_ui (mpz_t R, const mpz_t N, + unsigned long int D) + -- Function: unsigned long int mpz_tdiv_qr_ui (mpz_t Q, mpz_t R, + const mpz_t N, unsigned long int D) + -- Function: unsigned long int mpz_tdiv_ui (const mpz_t N, + unsigned long int D) + + -- Function: void mpz_tdiv_q_2exp (mpz_t Q, const mpz_t N, + mp_bitcnt_t B) + -- Function: void mpz_tdiv_r_2exp (mpz_t R, const mpz_t N, + mp_bitcnt_t B) + + + Divide N by D, forming a quotient Q and/or remainder R. For the + '2exp' functions, D=2^B. The rounding is in three styles, each + suiting different applications. + + * 'cdiv' rounds Q up towards +infinity, and R will have the + opposite sign to D. The 'c' stands for "ceil". + + * 'fdiv' rounds Q down towards -infinity, and R will have the + same sign as D. The 'f' stands for "floor". + + * 'tdiv' rounds Q towards zero, and R will have the same sign as + N. The 't' stands for "truncate". + + In all cases Q and R will satisfy N=Q*D+R, and R will satisfy + 0<=abs(R) 0 and that MOD is odd. + + This function is designed to take the same time and have the same + cache access patterns for any two same-size arguments, assuming + that function arguments are placed at the same position and that + the machine state is identical upon function entry. This function + is intended for cryptographic purposes, where resilience to + side-channel attacks is desired. + + -- Function: void mpz_pow_ui (mpz_t ROP, const mpz_t BASE, unsigned + long int EXP) + -- Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE, + unsigned long int EXP) + Set ROP to BASE raised to EXP. The case 0^0 yields 1. + + +File: gmp.info, Node: Integer Roots, Next: Number Theoretic Functions, Prev: Integer Exponentiation, Up: Integer Functions + +5.8 Root Extraction Functions +============================= + + -- Function: int mpz_root (mpz_t ROP, const mpz_t OP, unsigned long int + N) + Set ROP to the truncated integer part of the Nth root of OP. + Return non-zero if the computation was exact, i.e., if OP is ROP to + the Nth power. + + -- Function: void mpz_rootrem (mpz_t ROOT, mpz_t REM, const mpz_t U, + unsigned long int N) + Set ROOT to the truncated integer part of the Nth root of U. Set + REM to the remainder, U-ROOT**N. + + -- Function: void mpz_sqrt (mpz_t ROP, const mpz_t OP) + Set ROP to the truncated integer part of the square root of OP. + + -- Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, const mpz_t OP) + Set ROP1 to the truncated integer part of the square root of OP, + like 'mpz_sqrt'. Set ROP2 to the remainder OP-ROP1*ROP1, which + will be zero if OP is a perfect square. + + If ROP1 and ROP2 are the same variable, the results are undefined. + + -- Function: int mpz_perfect_power_p (const mpz_t OP) + Return non-zero if OP is a perfect power, i.e., if there exist + integers A and B, with B>1, such that OP equals A raised to the + power B. + + Under this definition both 0 and 1 are considered to be perfect + powers. Negative values of OP are accepted, but of course can only + be odd perfect powers. + + -- Function: int mpz_perfect_square_p (const mpz_t OP) + Return non-zero if OP is a perfect square, i.e., if the square root + of OP is an integer. Under this definition both 0 and 1 are + considered to be perfect squares. + + +File: gmp.info, Node: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions + +5.9 Number Theoretic Functions +============================== + + -- Function: int mpz_probab_prime_p (const mpz_t N, int REPS) + Determine whether N is prime. Return 2 if N is definitely prime, + return 1 if N is probably prime (without being certain), or return + 0 if N is definitely non-prime. + + This function performs some trial divisions, a Baillie-PSW probable + prime test, then REPS-24 Miller-Rabin probabilistic primality + tests. A higher REPS value will reduce the chances of a non-prime + being identified as "probably prime". A composite number will be + identified as a prime with an asymptotic probability of less than + 4^(-REPS). Reasonable values of REPS are between 15 and 50. + + GMP versions up to and including 6.1.2 did not use the Baillie-PSW + primality test. In those older versions of GMP, this function + performed REPS Miller-Rabin tests. + + -- Function: void mpz_nextprime (mpz_t ROP, const mpz_t OP) + Set ROP to the next prime greater than OP. + + -- Function: int mpz_prevprime (mpz_t ROP, const mpz_t OP) + Set ROP to the greatest prime less than OP. + + If a previous prime doesn't exist (i.e. OP < 3), rop is unchanged + and 0 is returned. + + Return 1 if ROP is a probably prime, and 2 if ROP is definitely + prime. + + These functions use a probabilistic algorithm to identify primes. + For practical purposes it's adequate, the chance of a composite + passing will be extremely small. + + -- Function: void mpz_gcd (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + Set ROP to the greatest common divisor of OP1 and OP2. The result + is always positive even if one or both input operands are negative. + Except if both inputs are zero; then this function defines gcd(0,0) + = 0. + + -- Function: unsigned long int mpz_gcd_ui (mpz_t ROP, const mpz_t OP1, + unsigned long int OP2) + Compute the greatest common divisor of OP1 and OP2. If ROP is not + 'NULL', store the result there. + + If the result is small enough to fit in an 'unsigned long int', it + is returned. If the result does not fit, 0 is returned, and the + result is equal to the argument OP1. Note that the result will + always fit if OP2 is non-zero. + + -- Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, const mpz_t A, + const mpz_t B) + Set G to the greatest common divisor of A and B, and in addition + set S and T to coefficients satisfying A*S + B*T = G. The value in + G is always positive, even if one or both of A and B are negative + (or zero if both inputs are zero). The values in S and T are + chosen such that normally, abs(S) < abs(B) / (2 G) and abs(T) < + abs(A) / (2 G), and these relations define S and T uniquely. There + are a few exceptional cases: + + If abs(A) = abs(B), then S = 0, T = sgn(B). + + Otherwise, S = sgn(A) if B = 0 or abs(B) = 2 G, and T = sgn(B) if A + = 0 or abs(A) = 2 G. + + In all cases, S = 0 if and only if G = abs(B), i.e., if B divides A + or A = B = 0. + + If T or G is 'NULL' then that value is not computed. + + -- Function: void mpz_lcm (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + -- Function: void mpz_lcm_ui (mpz_t ROP, const mpz_t OP1, unsigned long + OP2) + Set ROP to the least common multiple of OP1 and OP2. ROP is always + positive, irrespective of the signs of OP1 and OP2. ROP will be + zero if either OP1 or OP2 is zero. + + -- Function: int mpz_invert (mpz_t ROP, const mpz_t OP1, const mpz_t + OP2) + Compute the inverse of OP1 modulo OP2 and put the result in ROP. + If the inverse exists, the return value is non-zero and ROP will + satisfy 0 <= ROP < abs(OP2) (with ROP = 0 possible only when + abs(OP2) = 1, i.e., in the somewhat degenerate zero ring). If an + inverse doesn't exist the return value is zero and ROP is + undefined. The behaviour of this function is undefined when OP2 is + zero. + + -- Function: int mpz_jacobi (const mpz_t A, const mpz_t B) + Calculate the Jacobi symbol (A/B). This is defined only for B odd. + + -- Function: int mpz_legendre (const mpz_t A, const mpz_t P) + Calculate the Legendre symbol (A/P). This is defined only for P an + odd positive prime, and for such P it's identical to the Jacobi + symbol. + + -- Function: int mpz_kronecker (const mpz_t A, const mpz_t B) + -- Function: int mpz_kronecker_si (const mpz_t A, long B) + -- Function: int mpz_kronecker_ui (const mpz_t A, unsigned long B) + -- Function: int mpz_si_kronecker (long A, const mpz_t B) + -- Function: int mpz_ui_kronecker (unsigned long A, const mpz_t B) + Calculate the Jacobi symbol (A/B) with the Kronecker extension + (a/2)=(2/a) when a odd, or (a/2)=0 when a even. + + When B is odd the Jacobi symbol and Kronecker symbol are identical, + so 'mpz_kronecker_ui' etc can be used for mixed precision Jacobi + symbols too. + + For more information see Henri Cohen section 1.4.2 (*note + References::), or any number theory textbook. See also the example + program 'demos/qcn.c' which uses 'mpz_kronecker_ui'. + + -- Function: mp_bitcnt_t mpz_remove (mpz_t ROP, const mpz_t OP, const + mpz_t F) + Remove all occurrences of the factor F from OP and store the result + in ROP. The return value is how many such occurrences were + removed. + + -- Function: void mpz_fac_ui (mpz_t ROP, unsigned long int N) + -- Function: void mpz_2fac_ui (mpz_t ROP, unsigned long int N) + -- Function: void mpz_mfac_uiui (mpz_t ROP, unsigned long int N, + unsigned long int M) + Set ROP to the factorial of N: 'mpz_fac_ui' computes the plain + factorial N!, 'mpz_2fac_ui' computes the double-factorial N!!, and + 'mpz_mfac_uiui' the M-multi-factorial N!^(M). + + -- Function: void mpz_primorial_ui (mpz_t ROP, unsigned long int N) + Set ROP to the primorial of N, i.e. the product of all positive + prime numbers <=N. + + -- Function: void mpz_bin_ui (mpz_t ROP, const mpz_t N, unsigned long + int K) + -- Function: void mpz_bin_uiui (mpz_t ROP, unsigned long int N, + unsigned long int K) + Compute the binomial coefficient N over K and store the result in + ROP. Negative values of N are supported by 'mpz_bin_ui', using the + identity bin(-n,k) = (-1)^k * bin(n+k-1,k), see Knuth volume 1 + section 1.2.6 part G. + + -- Function: void mpz_fib_ui (mpz_t FN, unsigned long int N) + -- Function: void mpz_fib2_ui (mpz_t FN, mpz_t FNSUB1, unsigned long + int N) + 'mpz_fib_ui' sets FN to F[n], the Nth Fibonacci number. + 'mpz_fib2_ui' sets FN to F[n], and FNSUB1 to F[n-1]. + + These functions are designed for calculating isolated Fibonacci + numbers. When a sequence of values is wanted it's best to start + with 'mpz_fib2_ui' and iterate the defining F[n+1]=F[n]+F[n-1] or + similar. + + -- Function: void mpz_lucnum_ui (mpz_t LN, unsigned long int N) + -- Function: void mpz_lucnum2_ui (mpz_t LN, mpz_t LNSUB1, unsigned long + int N) + 'mpz_lucnum_ui' sets LN to L[n], the Nth Lucas number. + 'mpz_lucnum2_ui' sets LN to L[n], and LNSUB1 to L[n-1]. + + These functions are designed for calculating isolated Lucas + numbers. When a sequence of values is wanted it's best to start + with 'mpz_lucnum2_ui' and iterate the defining L[n+1]=L[n]+L[n-1] + or similar. + + The Fibonacci numbers and Lucas numbers are related sequences, so + it's never necessary to call both 'mpz_fib2_ui' and + 'mpz_lucnum2_ui'. The formulas for going from Fibonacci to Lucas + can be found in *note Lucas Numbers Algorithm::, the reverse is + straightforward too. + + +File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions + +5.10 Comparison Functions +========================= + + -- Function: int mpz_cmp (const mpz_t OP1, const mpz_t OP2) + -- Function: int mpz_cmp_d (const mpz_t OP1, double OP2) + -- Macro: int mpz_cmp_si (const mpz_t OP1, signed long int OP2) + -- Macro: int mpz_cmp_ui (const mpz_t OP1, unsigned long int OP2) + Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero if + OP1 = OP2, or a negative value if OP1 < OP2. + + 'mpz_cmp_ui' and 'mpz_cmp_si' are macros and will evaluate their + arguments more than once. 'mpz_cmp_d' can be called with an + infinity, but results are undefined for a NaN. + + -- Function: int mpz_cmpabs (const mpz_t OP1, const mpz_t OP2) + -- Function: int mpz_cmpabs_d (const mpz_t OP1, double OP2) + -- Function: int mpz_cmpabs_ui (const mpz_t OP1, unsigned long int OP2) + Compare the absolute values of OP1 and OP2. Return a positive + value if abs(OP1) > abs(OP2), zero if abs(OP1) = abs(OP2), or a + negative value if abs(OP1) < abs(OP2). + + 'mpz_cmpabs_d' can be called with an infinity, but results are + undefined for a NaN. + + -- Macro: int mpz_sgn (const mpz_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + + This function is actually implemented as a macro. It evaluates its + argument multiple times. + + +File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions + +5.11 Logical and Bit Manipulation Functions +=========================================== + +These functions behave as if two's complement arithmetic were used +(although sign-magnitude is the actual implementation). The least +significant bit is number 0. + + -- Function: void mpz_and (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + Set ROP to OP1 bitwise-and OP2. + + -- Function: void mpz_ior (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + Set ROP to OP1 bitwise inclusive-or OP2. + + -- Function: void mpz_xor (mpz_t ROP, const mpz_t OP1, const mpz_t OP2) + Set ROP to OP1 bitwise exclusive-or OP2. + + -- Function: void mpz_com (mpz_t ROP, const mpz_t OP) + Set ROP to the one's complement of OP. + + -- Function: mp_bitcnt_t mpz_popcount (const mpz_t OP) + If OP>=0, return the population count of OP, which is the number of + 1 bits in the binary representation. If OP<0, the number of 1s is + infinite, and the return value is the largest possible + 'mp_bitcnt_t'. + + -- Function: mp_bitcnt_t mpz_hamdist (const mpz_t OP1, const mpz_t OP2) + If OP1 and OP2 are both >=0 or both <0, return the hamming distance + between the two operands, which is the number of bit positions + where OP1 and OP2 have different bit values. If one operand is >=0 + and the other <0 then the number of bits different is infinite, and + the return value is the largest possible 'mp_bitcnt_t'. + + -- Function: mp_bitcnt_t mpz_scan0 (const mpz_t OP, mp_bitcnt_t + STARTING_BIT) + -- Function: mp_bitcnt_t mpz_scan1 (const mpz_t OP, mp_bitcnt_t + STARTING_BIT) + Scan OP, starting from bit STARTING_BIT, towards more significant + bits, until the first 0 or 1 bit (respectively) is found. Return + the index of the found bit. + + If the bit at STARTING_BIT is already what's sought, then + STARTING_BIT is returned. + + If there's no bit found, then the largest possible 'mp_bitcnt_t' is + returned. This will happen in 'mpz_scan0' past the end of a + negative number, or 'mpz_scan1' past the end of a nonnegative + number. + + -- Function: void mpz_setbit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) + Set bit BIT_INDEX in ROP. + + -- Function: void mpz_clrbit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) + Clear bit BIT_INDEX in ROP. + + -- Function: void mpz_combit (mpz_t ROP, mp_bitcnt_t BIT_INDEX) + Complement bit BIT_INDEX in ROP. + + -- Function: int mpz_tstbit (const mpz_t OP, mp_bitcnt_t BIT_INDEX) + Test bit BIT_INDEX in OP and return 0 or 1 accordingly. + + Shifting is also possible using multiplication (*note Integer +Arithmetic::) and division (*note Integer Division::), in particular the +'2exp' functions. + + +File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions + +5.12 Input and Output Functions +=============================== + +Functions that perform input from a stdio stream, and functions that +output to a stdio stream, of 'mpz' numbers. Passing a 'NULL' pointer +for a STREAM argument to any of these functions will make them read from +'stdin' and write to 'stdout', respectively. + + When using any of these functions, it is a good idea to include +'stdio.h' before 'gmp.h', since that will allow 'gmp.h' to define +prototypes for these functions. + + See also *note Formatted Output:: and *note Formatted Input::. + + -- Function: size_t mpz_out_str (FILE *STREAM, int BASE, const mpz_t + OP) + Output OP on stdio stream STREAM, as a string of digits in base + BASE. The base argument may vary from 2 to 62 or from -2 to -36. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + Return the number of bytes written, or if an error occurred, return + 0. + + -- Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE) + Input a possibly white-space preceded string in base BASE from + stdio stream STREAM, and put the read integer in ROP. + + The BASE may vary from 2 to 62, or if BASE is 0, then the leading + characters are used: '0x' and '0X' for hexadecimal, '0b' and '0B' + for binary, '0' for octal, or decimal otherwise. + + For bases up to 36, case is ignored; upper-case and lower-case + letters have the same value. For bases 37 to 62, upper-case + letters represent the usual 10..35 while lower-case letters + represent 36..61. + + Return the number of bytes read, or if an error occurred, return 0. + + -- Function: size_t mpz_out_raw (FILE *STREAM, const mpz_t OP) + Output OP on stdio stream STREAM, in raw binary format. The + integer is written in a portable format, with 4 bytes of size + information, and that many bytes of limbs. Both the size and the + limbs are written in decreasing significance order (i.e., in + big-endian). + + The output can be read with 'mpz_inp_raw'. + + Return the number of bytes written, or if an error occurred, return + 0. + + The output of this can not be read by 'mpz_inp_raw' from GMP 1, + because of changes necessary for compatibility between 32-bit and + 64-bit machines. + + -- Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM) + Input from stdio stream STREAM in the format written by + 'mpz_out_raw', and put the result in ROP. Return the number of + bytes read, or if an error occurred, return 0. + + This routine can read the output from 'mpz_out_raw' also from GMP + 1, in spite of changes necessary for compatibility between 32-bit + and 64-bit machines. + + +File: gmp.info, Node: Integer Random Numbers, Next: Integer Import and Export, Prev: I/O of Integers, Up: Integer Functions + +5.13 Random Number Functions +============================ + +The random number functions of GMP come in two groups; older functions +that rely on a global state, and newer functions that accept a state +parameter that is read and modified. Please see the *note Random Number +Functions:: for more information on how to use and not to use random +number functions. + + -- Function: void mpz_urandomb (mpz_t ROP, gmp_randstate_t STATE, + mp_bitcnt_t N) + Generate a uniformly distributed random integer in the range 0 to + 2^N-1, inclusive. + + The variable STATE must be initialized by calling one of the + 'gmp_randinit' functions (*note Random State Initialization::) + before invoking this function. + + -- Function: void mpz_urandomm (mpz_t ROP, gmp_randstate_t STATE, const + mpz_t N) + Generate a uniform random integer in the range 0 to N-1, inclusive. + + The variable STATE must be initialized by calling one of the + 'gmp_randinit' functions (*note Random State Initialization::) + before invoking this function. + + -- Function: void mpz_rrandomb (mpz_t ROP, gmp_randstate_t STATE, + mp_bitcnt_t N) + Generate a random integer with long strings of zeros and ones in + the binary representation. Useful for testing functions and + algorithms, since this kind of random numbers have proven to be + more likely to trigger corner-case bugs. The random number will be + in the range 2^(N-1) to 2^N-1, inclusive. + + The variable STATE must be initialized by calling one of the + 'gmp_randinit' functions (*note Random State Initialization::) + before invoking this function. + + -- Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE) + Generate a random integer of at most MAX_SIZE limbs. The generated + random number doesn't satisfy any particular requirements of + randomness. Negative random numbers are generated when MAX_SIZE is + negative. + + This function is obsolete. Use 'mpz_urandomb' or 'mpz_urandomm' + instead. + + -- Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE) + Generate a random integer of at most MAX_SIZE limbs, with long + strings of zeros and ones in the binary representation. Useful for + testing functions and algorithms, since this kind of random numbers + have proven to be more likely to trigger corner-case bugs. + Negative random numbers are generated when MAX_SIZE is negative. + + This function is obsolete. Use 'mpz_rrandomb' instead. + + +File: gmp.info, Node: Integer Import and Export, Next: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions + +5.14 Integer Import and Export +============================== + +'mpz_t' variables can be converted to and from arbitrary words of binary +data with the following functions. + + -- Function: void mpz_import (mpz_t ROP, size_t COUNT, int ORDER, + size_t SIZE, int ENDIAN, size_t NAILS, const void *OP) + Set ROP from an array of word data at OP. + + The parameters specify the format of the data. COUNT many words + are read, each SIZE bytes. ORDER can be 1 for most significant + word first or -1 for least significant first. Within each word + ENDIAN can be 1 for most significant byte first, -1 for least + significant first, or 0 for the native endianness of the host CPU. + The most significant NAILS bits of each word are skipped, this can + be 0 to use the full words. + + There is no sign taken from the data, ROP will simply be a positive + integer. An application can handle any sign itself, and apply it + for instance with 'mpz_neg'. + + There are no data alignment restrictions on OP, any address is + allowed. + + Here's an example converting an array of 'unsigned long' data, most + significant element first, and host byte order within each value. + + unsigned long a[20]; + /* Initialize Z and A */ + mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a); + + This example assumes the full 'sizeof' bytes are used for data in + the given type, which is usually true, and certainly true for + 'unsigned long' everywhere we know of. However on Cray vector + systems it may be noted that 'short' and 'int' are always stored in + 8 bytes (and with 'sizeof' indicating that) but use only 32 or 46 + bits. The NAILS feature can account for this, by passing for + instance '8*sizeof(int)-INT_BIT'. + + -- Function: void * mpz_export (void *ROP, size_t *COUNTP, int ORDER, + size_t SIZE, int ENDIAN, size_t NAILS, const mpz_t OP) + Fill ROP with word data from OP. + + The parameters specify the format of the data produced. Each word + will be SIZE bytes and ORDER can be 1 for most significant word + first or -1 for least significant first. Within each word ENDIAN + can be 1 for most significant byte first, -1 for least significant + first, or 0 for the native endianness of the host CPU. The most + significant NAILS bits of each word are unused and set to zero, + this can be 0 to produce full words. + + The number of words produced is written to '*COUNTP', or COUNTP can + be 'NULL' to discard the count. ROP must have enough space for the + data, or if ROP is 'NULL' then a result array of the necessary size + is allocated using the current GMP allocation function (*note + Custom Allocation::). In either case the return value is the + destination used, either ROP or the allocated block. + + If OP is non-zero then the most significant word produced will be + non-zero. If OP is zero then the count returned will be zero and + nothing written to ROP. If ROP is 'NULL' in this case, no block is + allocated, just 'NULL' is returned. + + The sign of OP is ignored, just the absolute value is exported. An + application can use 'mpz_sgn' to get the sign and handle it as + desired. (*note Integer Comparisons::) + + There are no data alignment restrictions on ROP, any address is + allowed. + + When an application is allocating space itself the required size + can be determined with a calculation like the following. Since + 'mpz_sizeinbase' always returns at least 1, 'count' here will be at + least one, which avoids any portability problems with 'malloc(0)', + though if 'z' is zero no space at all is actually needed (or + written). + + numb = 8*size - nail; + count = (mpz_sizeinbase (z, 2) + numb-1) / numb; + p = malloc (count * size); + + +File: gmp.info, Node: Miscellaneous Integer Functions, Next: Integer Special Functions, Prev: Integer Import and Export, Up: Integer Functions + +5.15 Miscellaneous Functions +============================ + + -- Function: int mpz_fits_ulong_p (const mpz_t OP) + -- Function: int mpz_fits_slong_p (const mpz_t OP) + -- Function: int mpz_fits_uint_p (const mpz_t OP) + -- Function: int mpz_fits_sint_p (const mpz_t OP) + -- Function: int mpz_fits_ushort_p (const mpz_t OP) + -- Function: int mpz_fits_sshort_p (const mpz_t OP) + Return non-zero iff the value of OP fits in an 'unsigned long int', + 'signed long int', 'unsigned int', 'signed int', 'unsigned short + int', or 'signed short int', respectively. Otherwise, return zero. + + -- Macro: int mpz_odd_p (const mpz_t OP) + -- Macro: int mpz_even_p (const mpz_t OP) + Determine whether OP is odd or even, respectively. Return non-zero + if yes, zero if no. These macros evaluate their argument more than + once. + + -- Function: size_t mpz_sizeinbase (const mpz_t OP, int BASE) + Return the size of OP measured in number of digits in the given + BASE. BASE can vary from 2 to 62. The sign of OP is ignored, just + the absolute value is used. The result will be either exact or 1 + too big. If BASE is a power of 2, the result is always exact. If + OP is zero the return value is always 1. + + This function can be used to determine the space required when + converting OP to a string. The right amount of allocation is + normally two more than the value returned by 'mpz_sizeinbase', one + extra for a minus sign and one for the null-terminator. + + It will be noted that 'mpz_sizeinbase(OP,2)' can be used to locate + the most significant 1 bit in OP, counting from 1. (Unlike the + bitwise functions which start from 0, *Note Logical and Bit + Manipulation Functions: Integer Logic and Bit Fiddling.) + + +File: gmp.info, Node: Integer Special Functions, Prev: Miscellaneous Integer Functions, Up: Integer Functions + +5.16 Special Functions +====================== + +The functions in this section are for various special purposes. Most +applications will not need them. + + -- Function: void mpz_array_init (mpz_t INTEGER_ARRAY, mp_size_t + ARRAY_SIZE, mp_size_t FIXED_NUM_BITS) + *This is an obsolete function. Do not use it.* + + -- Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC) + Change the space for INTEGER to NEW_ALLOC limbs. The value in + INTEGER is preserved if it fits, or is set to 0 if not. The return + value is not useful to applications and should be ignored. + + 'mpz_realloc2' is the preferred way to accomplish allocation + changes like this. 'mpz_realloc2' and '_mpz_realloc' are the same + except that '_mpz_realloc' takes its size in limbs. + + -- Function: mp_limb_t mpz_getlimbn (const mpz_t OP, mp_size_t N) + Return limb number N from OP. The sign of OP is ignored, just the + absolute value is used. The least significant limb is number 0. + + 'mpz_size' can be used to find how many limbs make up OP. + 'mpz_getlimbn' returns zero if N is outside the range 0 to + 'mpz_size(OP)-1'. + + -- Function: size_t mpz_size (const mpz_t OP) + Return the size of OP measured in number of limbs. If OP is zero, + the returned value will be zero. + + -- Function: const mp_limb_t * mpz_limbs_read (const mpz_t X) + Return a pointer to the limb array representing the absolute value + of X. The size of the array is 'mpz_size(X)'. Intended for read + access only. + + -- Function: mp_limb_t * mpz_limbs_write (mpz_t X, mp_size_t N) + -- Function: mp_limb_t * mpz_limbs_modify (mpz_t X, mp_size_t N) + Return a pointer to the limb array, intended for write access. The + array is reallocated as needed, to make room for N limbs. Requires + N > 0. The 'mpz_limbs_modify' function returns an array that holds + the old absolute value of X, while 'mpz_limbs_write' may destroy + the old value and return an array with unspecified contents. + + -- Function: void mpz_limbs_finish (mpz_t X, mp_size_t S) + Updates the internal size field of X. Used after writing to the + limb array pointer returned by 'mpz_limbs_write' or + 'mpz_limbs_modify' is completed. The array should contain abs(S) + valid limbs, representing the new absolute value for X, and the + sign of X is taken from the sign of S. This function never + reallocates X, so the limb pointer remains valid. + + void foo (mpz_t x) + { + mp_size_t n, i; + mp_limb_t *xp; + + n = mpz_size (x); + xp = mpz_limbs_modify (x, 2*n); + for (i = 0; i < n; i++) + xp[n+i] = xp[n-1-i]; + mpz_limbs_finish (x, mpz_sgn (x) < 0 ? - 2*n : 2*n); + } + + -- Function: mpz_srcptr mpz_roinit_n (mpz_t X, const mp_limb_t *XP, + mp_size_t XS) + Special initialization of X, using the given limb array and size. + X should be treated as read-only: it can be passed safely as input + to any mpz function, but not as an output. The array XP must point + to at least a readable limb, its size is abs(XS), and the sign of X + is the sign of XS. For convenience, the function returns X, but + cast to a const pointer type. + + void foo (mpz_t x) + { + static const mp_limb_t y[3] = { 0x1, 0x2, 0x3 }; + mpz_t tmp; + mpz_add (x, x, mpz_roinit_n (tmp, y, 3)); + } + + -- Macro: mpz_t MPZ_ROINIT_N (mp_limb_t *XP, mp_size_t XS) + This macro expands to an initializer which can be assigned to an + mpz_t variable. The limb array XP must point to at least a + readable limb, moreover, unlike the 'mpz_roinit_n' function, the + array must be normalized: if XS is non-zero, then 'XP[abs(XS)-1]' + must be non-zero. Intended primarily for constant values. Using + it for non-constant values requires a C compiler supporting C99. + + void foo (mpz_t x) + { + static const mp_limb_t ya[3] = { 0x1, 0x2, 0x3 }; + static const mpz_t y = MPZ_ROINIT_N ((mp_limb_t *) ya, 3); + + mpz_add (x, x, y); + } + + +File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top + +6 Rational Number Functions +*************************** + +This chapter describes the GMP functions for performing arithmetic on +rational numbers. These functions start with the prefix 'mpq_'. + + Rational numbers are stored in objects of type 'mpq_t'. + + All rational arithmetic functions assume operands have a canonical +form, and canonicalize their result. The canonical form means that the +denominator and the numerator have no common factors, and that the +denominator is positive. Zero has the unique representation 0/1. + + Pure assignment functions do not canonicalize the assigned variable. +It is the responsibility of the user to canonicalize the assigned +variable before any arithmetic operations are performed on that +variable. + + -- Function: void mpq_canonicalize (mpq_t OP) + Remove any factors that are common to the numerator and denominator + of OP, and make the denominator positive. + +* Menu: + +* Initializing Rationals:: +* Rational Conversions:: +* Rational Arithmetic:: +* Comparing Rationals:: +* Applying Integer Functions:: +* I/O of Rationals:: + + +File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions + +6.1 Initialization and Assignment Functions +=========================================== + + -- Function: void mpq_init (mpq_t X) + Initialize X and set it to 0/1. Each variable should normally only + be initialized once, or at least cleared out (using the function + 'mpq_clear') between each initialization. + + -- Function: void mpq_inits (mpq_t X, ...) + Initialize a NULL-terminated list of 'mpq_t' variables, and set + their values to 0/1. + + -- Function: void mpq_clear (mpq_t X) + Free the space occupied by X. Make sure to call this function for + all 'mpq_t' variables when you are done with them. + + -- Function: void mpq_clears (mpq_t X, ...) + Free the space occupied by a NULL-terminated list of 'mpq_t' + variables. + + -- Function: void mpq_set (mpq_t ROP, const mpq_t OP) + -- Function: void mpq_set_z (mpq_t ROP, const mpz_t OP) + Assign ROP from OP. + + -- Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1, + unsigned long int OP2) + -- Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned + long int OP2) + Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have + common factors, ROP has to be passed to 'mpq_canonicalize' before + any operations are performed on ROP. + + -- Function: int mpq_set_str (mpq_t ROP, const char *STR, int BASE) + Set ROP from a null-terminated string STR in the given BASE. + + The string can be an integer like "41" or a fraction like "41/152". + The fraction must be in canonical form (*note Rational Number + Functions::), or if not then 'mpq_canonicalize' must be called. + + The numerator and optional denominator are parsed the same as in + 'mpz_set_str' (*note Assigning Integers::). White space is allowed + in the string, and is simply ignored. The BASE can vary from 2 to + 62, or if BASE is 0 then the leading characters are used: '0x' or + '0X' for hex, '0b' or '0B' for binary, '0' for octal, or decimal + otherwise. Note that this is done separately for the numerator and + denominator, so for instance '0xEF/100' is 239/100, whereas + '0xEF/0x100' is 239/256. + + The return value is 0 if the entire string is a valid number, or -1 + if not. + + -- Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2) + Swap the values ROP1 and ROP2 efficiently. + + +File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions + +6.2 Conversion Functions +======================== + + -- Function: double mpq_get_d (const mpq_t OP) + Convert OP to a 'double', truncating if necessary (i.e. rounding + towards zero). + + If the exponent from the conversion is too big or too small to fit + a 'double' then the result is system dependent. For too big an + infinity is returned when available. For too small 0.0 is normally + returned. Hardware overflow, underflow and denorm traps may or may + not occur. + + -- Function: void mpq_set_d (mpq_t ROP, double OP) + -- Function: void mpq_set_f (mpq_t ROP, const mpf_t OP) + Set ROP to the value of OP. There is no rounding, this conversion + is exact. + + -- Function: char * mpq_get_str (char *STR, int BASE, const mpq_t OP) + Convert OP to a string of digits in base BASE. The base argument + may vary from 2 to 62 or from -2 to -36. The string will be of the + form 'num/den', or if the denominator is 1 then just 'num'. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + If STR is 'NULL', the result string is allocated using the current + allocation function (*note Custom Allocation::). The block will be + 'strlen(str)+1' bytes, that being exactly enough for the string and + null-terminator. + + If STR is not 'NULL', it should point to a block of storage large + enough for the result, that being + + mpz_sizeinbase (mpq_numref(OP), BASE) + + mpz_sizeinbase (mpq_denref(OP), BASE) + 3 + + The three extra bytes are for a possible minus sign, possible + slash, and the null-terminator. + + A pointer to the result string is returned, being either the + allocated block, or the given STR. + + +File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions + +6.3 Arithmetic Functions +======================== + + -- Function: void mpq_add (mpq_t SUM, const mpq_t ADDEND1, const mpq_t + ADDEND2) + Set SUM to ADDEND1 + ADDEND2. + + -- Function: void mpq_sub (mpq_t DIFFERENCE, const mpq_t MINUEND, const + mpq_t SUBTRAHEND) + Set DIFFERENCE to MINUEND - SUBTRAHEND. + + -- Function: void mpq_mul (mpq_t PRODUCT, const mpq_t MULTIPLIER, const + mpq_t MULTIPLICAND) + Set PRODUCT to MULTIPLIER times MULTIPLICAND. + + -- Function: void mpq_mul_2exp (mpq_t ROP, const mpq_t OP1, mp_bitcnt_t + OP2) + Set ROP to OP1 times 2 raised to OP2. + + -- Function: void mpq_div (mpq_t QUOTIENT, const mpq_t DIVIDEND, const + mpq_t DIVISOR) + Set QUOTIENT to DIVIDEND/DIVISOR. + + -- Function: void mpq_div_2exp (mpq_t ROP, const mpq_t OP1, mp_bitcnt_t + OP2) + Set ROP to OP1 divided by 2 raised to OP2. + + -- Function: void mpq_neg (mpq_t NEGATED_OPERAND, const mpq_t OPERAND) + Set NEGATED_OPERAND to -OPERAND. + + -- Function: void mpq_abs (mpq_t ROP, const mpq_t OP) + Set ROP to the absolute value of OP. + + -- Function: void mpq_inv (mpq_t INVERTED_NUMBER, const mpq_t NUMBER) + Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero, + this routine will divide by zero. + + +File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions + +6.4 Comparison Functions +======================== + + -- Function: int mpq_cmp (const mpq_t OP1, const mpq_t OP2) + -- Function: int mpq_cmp_z (const mpq_t OP1, const mpz_t OP2) + Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero if + OP1 = OP2, and a negative value if OP1 < OP2. + + To determine if two rationals are equal, 'mpq_equal' is faster than + 'mpq_cmp'. + + -- Macro: int mpq_cmp_ui (const mpq_t OP1, unsigned long int NUM2, + unsigned long int DEN2) + -- Macro: int mpq_cmp_si (const mpq_t OP1, long int NUM2, unsigned long + int DEN2) + Compare OP1 and NUM2/DEN2. Return a positive value if OP1 > + NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 < + NUM2/DEN2. + + NUM2 and DEN2 are allowed to have common factors. + + These functions are implemented as macros and evaluate their + arguments multiple times. + + -- Macro: int mpq_sgn (const mpq_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + + This function is actually implemented as a macro. It evaluates its + argument multiple times. + + -- Function: int mpq_equal (const mpq_t OP1, const mpq_t OP2) + Return non-zero if OP1 and OP2 are equal, zero if they are + non-equal. Although 'mpq_cmp' can be used for the same purpose, + this function is much faster. + + +File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions + +6.5 Applying Integer Functions to Rationals +=========================================== + +The set of 'mpq' functions is quite small. In particular, there are few +functions for either input or output. The following functions give +direct access to the numerator and denominator of an 'mpq_t'. + + Note that if an assignment to the numerator and/or denominator could +take an 'mpq_t' out of the canonical form described at the start of this +chapter (*note Rational Number Functions::) then 'mpq_canonicalize' must +be called before any other 'mpq' functions are applied to that 'mpq_t'. + + -- Macro: mpz_ptr mpq_numref (const mpq_t OP) + -- Macro: mpz_ptr mpq_denref (const mpq_t OP) + Return a reference to the numerator and denominator of OP, + respectively. The 'mpz' functions can be used on the result of + these macros. Such calls may modify the numerator or denominator. + However, care should be taken so that OP remains in canonical form + prior to a possible later call to an 'mpq' function. + + -- Function: void mpq_get_num (mpz_t NUMERATOR, const mpq_t RATIONAL) + -- Function: void mpq_get_den (mpz_t DENOMINATOR, const mpq_t RATIONAL) + -- Function: void mpq_set_num (mpq_t RATIONAL, const mpz_t NUMERATOR) + -- Function: void mpq_set_den (mpq_t RATIONAL, const mpz_t DENOMINATOR) + Get or set the numerator or denominator of a rational. These + functions are equivalent to calling 'mpz_set' with an appropriate + 'mpq_numref' or 'mpq_denref'. Direct use of 'mpq_numref' or + 'mpq_denref' is recommended instead of these functions. + + +File: gmp.info, Node: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions + +6.6 Input and Output Functions +============================== + +Functions that perform input from a stdio stream, and functions that +output to a stdio stream, of 'mpq' numbers. Passing a 'NULL' pointer +for a STREAM argument to any of these functions will make them read from +'stdin' and write to 'stdout', respectively. + + When using any of these functions, it is a good idea to include +'stdio.h' before 'gmp.h', since that will allow 'gmp.h' to define +prototypes for these functions. + + See also *note Formatted Output:: and *note Formatted Input::. + + -- Function: size_t mpq_out_str (FILE *STREAM, int BASE, const mpq_t + OP) + Output OP on stdio stream STREAM, as a string of digits in base + BASE. The base argument may vary from 2 to 62 or from -2 to -36. + Output is in the form 'num/den' or if the denominator is 1 then + just 'num'. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + Return the number of bytes written, or if an error occurred, return + 0. + + -- Function: size_t mpq_inp_str (mpq_t ROP, FILE *STREAM, int BASE) + Read a string of digits from STREAM and convert them to a rational + in ROP. Any initial white-space characters are read and discarded. + Return the number of characters read (including white space), or 0 + if a rational could not be read. + + The input can be a fraction like '17/63' or just an integer like + '123'. Reading stops at the first character not in this form, and + white space is not permitted within the string. If the input might + not be in canonical form, then 'mpq_canonicalize' must be called + (*note Rational Number Functions::). + + The BASE can be between 2 and 62, or can be 0 in which case the + leading characters of the string determine the base, '0x' or '0X' + for hexadecimal, '0b' and '0B' for binary, '0' for octal, or + decimal otherwise. The leading characters are examined separately + for the numerator and denominator of a fraction, so for instance + '0x10/11' is 16/11, whereas '0x10/0x11' is 16/17. + + +File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top + +7 Floating-point Functions +************************** + +GMP floating point numbers are stored in objects of type 'mpf_t' and +functions operating on them have an 'mpf_' prefix. + + The mantissa of each float has a user-selectable precision, in +practice only limited by available memory. Each variable has its own +precision, and that can be increased or decreased at any time. This +selectable precision is a minimum value, GMP rounds it up to a whole +limb. + + The accuracy of a calculation is determined by the priorly set +precision of the destination variable and the numeric values of the +input variables. Input variables' set precisions do not affect +calculations (except indirectly as their values might have been affected +when they were assigned). + + The exponent of each float has fixed precision, one machine word on +most systems. In the current implementation the exponent is a count of +limbs, so for example on a 32-bit system this means a range of roughly +2^-68719476768 to 2^68719476736, or on a 64-bit system this will be much +greater. Note however that 'mpf_get_str' can only return an exponent +which fits an 'mp_exp_t' and currently 'mpf_set_str' doesn't accept +exponents bigger than a 'long'. + + Each variable keeps track of the mantissa data actually in use. This +means that if a float is exactly represented in only a few bits then +only those bits will be used in a calculation, even if the variable's +selected precision is high. This is a performance optimization; it does +not affect the numeric results. + + Internally, GMP sometimes calculates with higher precision than that +of the destination variable in order to limit errors. Final results are +always truncated to the destination variable's precision. + + The mantissa is stored in binary. One consequence of this is that +decimal fractions like 0.1 cannot be represented exactly. The same is +true of plain IEEE 'double' floats. This makes both highly unsuitable +for calculations involving money or other values that should be exact +decimal fractions. (Suitably scaled integers, or perhaps rationals, are +better choices.) + + The 'mpf' functions and variables have no special notion of infinity +or not-a-number, and applications must take care not to overflow the +exponent or results will be unpredictable. + + Note that the 'mpf' functions are _not_ intended as a smooth +extension to IEEE P754 arithmetic. In particular results obtained on +one computer often differ from the results on a computer with a +different word size. + + New projects should consider using the GMP extension library MPFR +() instead. MPFR provides well-defined precision +and accurate rounding, and thereby naturally extends IEEE P754. + +* Menu: + +* Initializing Floats:: +* Assigning Floats:: +* Simultaneous Float Init & Assign:: +* Converting Floats:: +* Float Arithmetic:: +* Float Comparison:: +* I/O of Floats:: +* Miscellaneous Float Functions:: + + +File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions + +7.1 Initialization Functions +============================ + + -- Function: void mpf_set_default_prec (mp_bitcnt_t PREC) + Set the default precision to be *at least* PREC bits. All + subsequent calls to 'mpf_init' will use this precision, but + previously initialized variables are unaffected. + + -- Function: mp_bitcnt_t mpf_get_default_prec (void) + Return the default precision actually used. + + An 'mpf_t' object must be initialized before storing the first value +in it. The functions 'mpf_init' and 'mpf_init2' are used for that +purpose. + + -- Function: void mpf_init (mpf_t X) + Initialize X to 0. Normally, a variable should be initialized once + only or at least be cleared, using 'mpf_clear', between + initializations. The precision of X is undefined unless a default + precision has already been established by a call to + 'mpf_set_default_prec'. + + -- Function: void mpf_init2 (mpf_t X, mp_bitcnt_t PREC) + Initialize X to 0 and set its precision to be *at least* PREC bits. + Normally, a variable should be initialized once only or at least be + cleared, using 'mpf_clear', between initializations. + + -- Function: void mpf_inits (mpf_t X, ...) + Initialize a NULL-terminated list of 'mpf_t' variables, and set + their values to 0. The precision of the initialized variables is + undefined unless a default precision has already been established + by a call to 'mpf_set_default_prec'. + + -- Function: void mpf_clear (mpf_t X) + Free the space occupied by X. Make sure to call this function for + all 'mpf_t' variables when you are done with them. + + -- Function: void mpf_clears (mpf_t X, ...) + Free the space occupied by a NULL-terminated list of 'mpf_t' + variables. + + Here is an example on how to initialize floating-point variables: + { + mpf_t x, y; + mpf_init (x); /* use default precision */ + mpf_init2 (y, 256); /* precision _at least_ 256 bits */ + ... + /* Unless the program is about to exit, do ... */ + mpf_clear (x); + mpf_clear (y); + } + + The following three functions are useful for changing the precision +during a calculation. A typical use would be for adjusting the +precision gradually in iterative algorithms like Newton-Raphson, making +the computation precision closely match the actual accurate part of the +numbers. + + -- Function: mp_bitcnt_t mpf_get_prec (const mpf_t OP) + Return the current precision of OP, in bits. + + -- Function: void mpf_set_prec (mpf_t ROP, mp_bitcnt_t PREC) + Set the precision of ROP to be *at least* PREC bits. The value in + ROP will be truncated to the new precision. + + This function requires a call to 'realloc', and so should not be + used in a tight loop. + + -- Function: void mpf_set_prec_raw (mpf_t ROP, mp_bitcnt_t PREC) + Set the precision of ROP to be *at least* PREC bits, without + changing the memory allocated. + + PREC must be no more than the allocated precision for ROP, that + being the precision when ROP was initialized, or in the most recent + 'mpf_set_prec'. + + The value in ROP is unchanged, and in particular if it had a higher + precision than PREC it will retain that higher precision. New + values written to ROP will use the new PREC. + + Before calling 'mpf_clear' or the full 'mpf_set_prec', another + 'mpf_set_prec_raw' call must be made to restore ROP to its original + allocated precision. Failing to do so will have unpredictable + results. + + 'mpf_get_prec' can be used before 'mpf_set_prec_raw' to get the + original allocated precision. After 'mpf_set_prec_raw' it reflects + the PREC value set. + + 'mpf_set_prec_raw' is an efficient way to use an 'mpf_t' variable + at different precisions during a calculation, perhaps to gradually + increase precision in an iteration, or just to use various + different precisions for different purposes during a calculation. + + +File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions + +7.2 Assignment Functions +======================== + +These functions assign new values to already initialized floats (*note +Initializing Floats::). + + -- Function: void mpf_set (mpf_t ROP, const mpf_t OP) + -- Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP) + -- Function: void mpf_set_si (mpf_t ROP, signed long int OP) + -- Function: void mpf_set_d (mpf_t ROP, double OP) + -- Function: void mpf_set_z (mpf_t ROP, const mpz_t OP) + -- Function: void mpf_set_q (mpf_t ROP, const mpq_t OP) + Set the value of ROP from OP. + + -- Function: int mpf_set_str (mpf_t ROP, const char *STR, int BASE) + Set the value of ROP from the string in STR. The string is of the + form 'M@N' or, if the base is 10 or less, alternatively 'MeN'. 'M' + is the mantissa and 'N' is the exponent. The mantissa is always in + the specified base. The exponent is either in the specified base + or, if BASE is negative, in decimal. The decimal point expected is + taken from the current locale, on systems providing 'localeconv'. + + The argument BASE may be in the ranges 2 to 62, or -62 to -2. + Negative values are used to specify that the exponent is in + decimal. + + For bases up to 36, case is ignored; upper-case and lower-case + letters have the same value; for bases 37 to 62, upper-case letters + represent the usual 10..35 while lower-case letters represent + 36..61. + + Unlike the corresponding 'mpz' function, the base will not be + determined from the leading characters of the string if BASE is 0. + This is so that numbers like '0.23' are not interpreted as octal. + + White space is allowed in the string, and is simply ignored. [This + is not really true; white-space is ignored in the beginning of the + string and within the mantissa, but not in other places, such as + after a minus sign or in the exponent. We are considering changing + the definition of this function, making it fail when there is any + white-space in the input, since that makes a lot of sense. Please + tell us your opinion about this change. Do you really want it to + accept "3 14" as meaning 314 as it does now?] + + This function returns 0 if the entire string is a valid number in + base BASE. Otherwise it returns -1. + + -- Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2) + Swap ROP1 and ROP2 efficiently. Both the values and the precisions + of the two variables are swapped. + + +File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions + +7.3 Combined Initialization and Assignment Functions +==================================================== + +For convenience, GMP provides a parallel series of initialize-and-set +functions which initialize the output and then store the value there. +These functions' names have the form 'mpf_init_set...' + + Once the float has been initialized by any of the 'mpf_init_set...' +functions, it can be used as the source or destination operand for the +ordinary float functions. Don't use an initialize-and-set function on a +variable already initialized! + + -- Function: void mpf_init_set (mpf_t ROP, const mpf_t OP) + -- Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP) + -- Function: void mpf_init_set_si (mpf_t ROP, signed long int OP) + -- Function: void mpf_init_set_d (mpf_t ROP, double OP) + Initialize ROP and set its value from OP. + + The precision of ROP will be taken from the active default + precision, as set by 'mpf_set_default_prec'. + + -- Function: int mpf_init_set_str (mpf_t ROP, const char *STR, int + BASE) + Initialize ROP and set its value from the string in STR. See + 'mpf_set_str' above for details on the assignment operation. + + Note that ROP is initialized even if an error occurs. (I.e., you + have to call 'mpf_clear' for it.) + + The precision of ROP will be taken from the active default + precision, as set by 'mpf_set_default_prec'. + + +File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions + +7.4 Conversion Functions +======================== + + -- Function: double mpf_get_d (const mpf_t OP) + Convert OP to a 'double', truncating if necessary (i.e. rounding + towards zero). + + If the exponent in OP is too big or too small to fit a 'double' + then the result is system dependent. For too big an infinity is + returned when available. For too small 0.0 is normally returned. + Hardware overflow, underflow and denorm traps may or may not occur. + + -- Function: double mpf_get_d_2exp (signed long int *EXP, const mpf_t + OP) + Convert OP to a 'double', truncating if necessary (i.e. rounding + towards zero), and with an exponent returned separately. + + The return value is in the range 0.5<=abs(D)<1 and the exponent is + stored to '*EXP'. D * 2^EXP is the (truncated) OP value. If OP is + zero, the return is 0.0 and 0 is stored to '*EXP'. + + This is similar to the standard C 'frexp' function (*note + (libc)Normalization Functions::). + + -- Function: long mpf_get_si (const mpf_t OP) + -- Function: unsigned long mpf_get_ui (const mpf_t OP) + Convert OP to a 'long' or 'unsigned long', truncating any fraction + part. If OP is too big for the return type, the result is + undefined. + + See also 'mpf_fits_slong_p' and 'mpf_fits_ulong_p' (*note + Miscellaneous Float Functions::). + + -- Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE, + size_t N_DIGITS, const mpf_t OP) + Convert OP to a string of digits in base BASE. The base argument + may vary from 2 to 62 or from -2 to -36. Up to N_DIGITS digits + will be generated. Trailing zeros are not returned. No more + digits than can be accurately represented by OP are ever generated. + If N_DIGITS is 0 then that accurate maximum number of digits are + generated. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + If STR is 'NULL', the result string is allocated using the current + allocation function (*note Custom Allocation::). The block will be + 'strlen(str)+1' bytes, that being exactly enough for the string and + null-terminator. + + If STR is not 'NULL', it should point to a block of N_DIGITS + 2 + bytes, that being enough for the mantissa, a possible minus sign, + and a null-terminator. When N_DIGITS is 0 to get all significant + digits, an application won't be able to know the space required, + and STR should be 'NULL' in that case. + + The generated string is a fraction, with an implicit radix point + immediately to the left of the first digit. The applicable + exponent is written through the EXPPTR pointer. For example, the + number 3.1416 would be returned as string "31416" and exponent 1. + + When OP is zero, an empty string is produced and the exponent + returned is 0. + + A pointer to the result string is returned, being either the + allocated block or the given STR. + + +File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions + +7.5 Arithmetic Functions +======================== + + -- Function: void mpf_add (mpf_t ROP, const mpf_t OP1, const mpf_t OP2) + -- Function: void mpf_add_ui (mpf_t ROP, const mpf_t OP1, unsigned long + int OP2) + Set ROP to OP1 + OP2. + + -- Function: void mpf_sub (mpf_t ROP, const mpf_t OP1, const mpf_t OP2) + -- Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, const + mpf_t OP2) + -- Function: void mpf_sub_ui (mpf_t ROP, const mpf_t OP1, unsigned long + int OP2) + Set ROP to OP1 - OP2. + + -- Function: void mpf_mul (mpf_t ROP, const mpf_t OP1, const mpf_t OP2) + -- Function: void mpf_mul_ui (mpf_t ROP, const mpf_t OP1, unsigned long + int OP2) + Set ROP to OP1 times OP2. + + Division is undefined if the divisor is zero, and passing a zero +divisor to the divide functions will make these functions intentionally +divide by zero. This lets the user handle arithmetic exceptions in +these functions in the same manner as other arithmetic exceptions. + + -- Function: void mpf_div (mpf_t ROP, const mpf_t OP1, const mpf_t OP2) + -- Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, const + mpf_t OP2) + -- Function: void mpf_div_ui (mpf_t ROP, const mpf_t OP1, unsigned long + int OP2) + Set ROP to OP1/OP2. + + -- Function: void mpf_sqrt (mpf_t ROP, const mpf_t OP) + -- Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP) + Set ROP to the square root of OP. + + -- Function: void mpf_pow_ui (mpf_t ROP, const mpf_t OP1, unsigned long + int OP2) + Set ROP to OP1 raised to the power OP2. + + -- Function: void mpf_neg (mpf_t ROP, const mpf_t OP) + Set ROP to -OP. + + -- Function: void mpf_abs (mpf_t ROP, const mpf_t OP) + Set ROP to the absolute value of OP. + + -- Function: void mpf_mul_2exp (mpf_t ROP, const mpf_t OP1, mp_bitcnt_t + OP2) + Set ROP to OP1 times 2 raised to OP2. + + -- Function: void mpf_div_2exp (mpf_t ROP, const mpf_t OP1, mp_bitcnt_t + OP2) + Set ROP to OP1 divided by 2 raised to OP2. + + +File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions + +7.6 Comparison Functions +======================== + + -- Function: int mpf_cmp (const mpf_t OP1, const mpf_t OP2) + -- Function: int mpf_cmp_z (const mpf_t OP1, const mpz_t OP2) + -- Function: int mpf_cmp_d (const mpf_t OP1, double OP2) + -- Function: int mpf_cmp_ui (const mpf_t OP1, unsigned long int OP2) + -- Function: int mpf_cmp_si (const mpf_t OP1, signed long int OP2) + Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero if + OP1 = OP2, and a negative value if OP1 < OP2. + + 'mpf_cmp_d' can be called with an infinity, but results are + undefined for a NaN. + + -- Function: int mpf_eq (const mpf_t OP1, const mpf_t OP2, mp_bitcnt_t + op3) + *This function is mathematically ill-defined and should not be + used.* + + Return non-zero if the first OP3 bits of OP1 and OP2 are equal, + zero otherwise. Note that numbers like e.g., 256 (binary + 100000000) and 255 (binary 11111111) will never be equal by this + function's measure, and furthermore that 0 will only be equal to + itself. + + -- Function: void mpf_reldiff (mpf_t ROP, const mpf_t OP1, const mpf_t + OP2) + Compute the relative difference between OP1 and OP2 and store the + result in ROP. This is abs(OP1-OP2)/OP1. + + -- Macro: int mpf_sgn (const mpf_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + + This function is actually implemented as a macro. It evaluates its + argument multiple times. + + +File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions + +7.7 Input and Output Functions +============================== + +Functions that perform input from a stdio stream, and functions that +output to a stdio stream, of 'mpf' numbers. Passing a 'NULL' pointer +for a STREAM argument to any of these functions will make them read from +'stdin' and write to 'stdout', respectively. + + When using any of these functions, it is a good idea to include +'stdio.h' before 'gmp.h', since that will allow 'gmp.h' to define +prototypes for these functions. + + See also *note Formatted Output:: and *note Formatted Input::. + + -- Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t + N_DIGITS, const mpf_t OP) + Print OP to STREAM, as a string of digits. Return the number of + bytes written, or if an error occurred, return 0. + + The mantissa is prefixed with an '0.' and is in the given BASE, + which may vary from 2 to 62 or from -2 to -36. An exponent is then + printed, separated by an 'e', or if the base is greater than 10 + then by an '@'. The exponent is always in decimal. The decimal + point follows the current locale, on systems providing + 'localeconv'. + + For BASE in the range 2..36, digits and lower-case letters are + used; for -2..-36, digits and upper-case letters are used; for + 37..62, digits, upper-case letters, and lower-case letters (in that + significance order) are used. + + Up to N_DIGITS will be printed from the mantissa, except that no + more digits than are accurately representable by OP will be + printed. N_DIGITS can be 0 to select that accurate maximum. + + -- Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE) + Read a string in base BASE from STREAM, and put the read float in + ROP. The string is of the form 'M@N' or, if the base is 10 or + less, alternatively 'MeN'. 'M' is the mantissa and 'N' is the + exponent. The mantissa is always in the specified base. The + exponent is either in the specified base or, if BASE is negative, + in decimal. The decimal point expected is taken from the current + locale, on systems providing 'localeconv'. + + The argument BASE may be in the ranges 2 to 36, or -36 to -2. + Negative values are used to specify that the exponent is in + decimal. + + Unlike the corresponding 'mpz' function, the base will not be + determined from the leading characters of the string if BASE is 0. + This is so that numbers like '0.23' are not interpreted as octal. + + Return the number of bytes read, or if an error occurred, return 0. + + +File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions + +7.8 Miscellaneous Functions +=========================== + + -- Function: void mpf_ceil (mpf_t ROP, const mpf_t OP) + -- Function: void mpf_floor (mpf_t ROP, const mpf_t OP) + -- Function: void mpf_trunc (mpf_t ROP, const mpf_t OP) + Set ROP to OP rounded to an integer. 'mpf_ceil' rounds to the next + higher integer, 'mpf_floor' to the next lower, and 'mpf_trunc' to + the integer towards zero. + + -- Function: int mpf_integer_p (const mpf_t OP) + Return non-zero if OP is an integer. + + -- Function: int mpf_fits_ulong_p (const mpf_t OP) + -- Function: int mpf_fits_slong_p (const mpf_t OP) + -- Function: int mpf_fits_uint_p (const mpf_t OP) + -- Function: int mpf_fits_sint_p (const mpf_t OP) + -- Function: int mpf_fits_ushort_p (const mpf_t OP) + -- Function: int mpf_fits_sshort_p (const mpf_t OP) + Return non-zero if OP would fit in the respective C data type, when + truncated to an integer. + + -- Function: void mpf_urandomb (mpf_t ROP, gmp_randstate_t STATE, + mp_bitcnt_t NBITS) + Generate a uniformly distributed random float in ROP, such that 0 + <= ROP < 1, with NBITS significant bits in the mantissa or less if + the precision of ROP is smaller. + + The variable STATE must be initialized by calling one of the + 'gmp_randinit' functions (*note Random State Initialization::) + before invoking this function. + + -- Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t + EXP) + Generate a random float of at most MAX_SIZE limbs, with long + strings of zeros and ones in the binary representation. The + exponent of the number is in the interval -EXP to EXP (in limbs). + This function is useful for testing functions and algorithms, since + these kind of random numbers have proven to be more likely to + trigger corner-case bugs. Negative random numbers are generated + when MAX_SIZE is negative. + + +File: gmp.info, Node: Low-level Functions, Next: Random Number Functions, Prev: Floating-point Functions, Up: Top + +8 Low-level Functions +********************* + +This chapter describes low-level GMP functions, used to implement the +high-level GMP functions, but also intended for time-critical user code. + + These functions start with the prefix 'mpn_'. + + The 'mpn' functions are designed to be as fast as possible, *not* to +provide a coherent calling interface. The different functions have +somewhat similar interfaces, but there are variations that make them +hard to use. These functions do as little as possible apart from the +real multiple precision computation, so that no time is spent on things +that not all callers need. + + A source operand is specified by a pointer to the least significant +limb and a limb count. A destination operand is specified by just a +pointer. It is the responsibility of the caller to ensure that the +destination has enough space for storing the result. + + With this way of specifying operands, it is possible to perform +computations on subranges of an argument, and store the result into a +subrange of a destination. + + A common requirement for all functions is that each source area needs +at least one limb. No size argument may be zero. Unless otherwise +stated, in-place operations are allowed where source and destination are +the same, but not where they only partly overlap. + + The 'mpn' functions are the base for the implementation of the +'mpz_', 'mpf_', and 'mpq_' functions. + + This example adds the number beginning at S1P and the number +beginning at S2P and writes the sum at DESTP. All areas have N limbs. + + cy = mpn_add_n (destp, s1p, s2p, n) + + It should be noted that the 'mpn' functions make no attempt to +identify high or low zero limbs on their operands, or other special +forms. On random data such cases will be unlikely and it'd be wasteful +for every function to check every time. An application knowing +something about its data can take steps to trim or perhaps split its +calculations. + + +In the notation used below, a source operand is identified by the +pointer to the least significant limb, and the limb count in braces. +For example, {S1P, S1N}. + + -- Function: mp_limb_t mpn_add_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Add {S1P, N} and {S2P, N}, and write the N least significant limbs + of the result to RP. Return carry, either 0 or 1. + + This is the lowest-level function for addition. It is the + preferred function for addition, since it is written in assembly + for most CPUs. For addition of a variable to itself (i.e., S1P + equals S2P) use 'mpn_lshift' with a count of 1 for optimal speed. + + -- Function: mp_limb_t mpn_add_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Add {S1P, N} and S2LIMB, and write the N least significant limbs of + the result to RP. Return carry, either 0 or 1. + + -- Function: mp_limb_t mpn_add (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Add {S1P, S1N} and {S2P, S2N}, and write the S1N least significant + limbs of the result to RP. Return carry, either 0 or 1. + + This function requires that S1N is greater than or equal to S2N. + + -- Function: mp_limb_t mpn_sub_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Subtract {S2P, N} from {S1P, N}, and write the N least significant + limbs of the result to RP. Return borrow, either 0 or 1. + + This is the lowest-level function for subtraction. It is the + preferred function for subtraction, since it is written in assembly + for most CPUs. + + -- Function: mp_limb_t mpn_sub_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Subtract S2LIMB from {S1P, N}, and write the N least significant + limbs of the result to RP. Return borrow, either 0 or 1. + + -- Function: mp_limb_t mpn_sub (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Subtract {S2P, S2N} from {S1P, S1N}, and write the S1N least + significant limbs of the result to RP. Return borrow, either 0 or + 1. + + This function requires that S1N is greater than or equal to S2N. + + -- Function: mp_limb_t mpn_neg (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N) + Perform the negation of {SP, N}, and write the result to {RP, N}. + This is equivalent to calling 'mpn_sub_n' with an N-limb zero + minuend and passing {SP, N} as subtrahend. Return borrow, either 0 + or 1. + + -- Function: void mpn_mul_n (mp_limb_t *RP, const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Multiply {S1P, N} and {S2P, N}, and write the 2*N-limb result to + RP. + + The destination has to have space for 2*N limbs, even if the + product's most significant limb is zero. No overlap is permitted + between the destination and either source. + + If the two input operands are the same, use 'mpn_sqr'. + + -- Function: mp_limb_t mpn_mul (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Multiply {S1P, S1N} and {S2P, S2N}, and write the (S1N+S2N)-limb + result to RP. Return the most significant limb of the result. + + The destination has to have space for S1N + S2N limbs, even if the + product's most significant limb is zero. No overlap is permitted + between the destination and either source. + + This function requires that S1N is greater than or equal to S2N. + + -- Function: void mpn_sqr (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N) + Compute the square of {S1P, N} and write the 2*N-limb result to RP. + + The destination has to have space for 2N limbs, even if the + result's most significant limb is zero. No overlap is permitted + between the destination and the source. + + -- Function: mp_limb_t mpn_mul_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} by S2LIMB, and write the N least significant + limbs of the product to RP. Return the most significant limb of + the product. {S1P, N} and {RP, N} are allowed to overlap provided + RP <= S1P. + + This is a low-level function that is a building block for general + multiplication as well as other operations in GMP. It is written + in assembly for most CPUs. + + Don't call this function if S2LIMB is a power of 2; use + 'mpn_lshift' with a count equal to the logarithm of S2LIMB instead, + for optimal speed. + + -- Function: mp_limb_t mpn_addmul_1 (mp_limb_t *RP, const mp_limb_t + *S1P, mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} and S2LIMB, and add the N least significant limbs + of the product to {RP, N} and write the result to RP. Return the + most significant limb of the product, plus carry-out from the + addition. {S1P, N} and {RP, N} are allowed to overlap provided RP + <= S1P. + + This is a low-level function that is a building block for general + multiplication as well as other operations in GMP. It is written + in assembly for most CPUs. + + -- Function: mp_limb_t mpn_submul_1 (mp_limb_t *RP, const mp_limb_t + *S1P, mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} and S2LIMB, and subtract the N least significant + limbs of the product from {RP, N} and write the result to RP. + Return the most significant limb of the product, plus borrow-out + from the subtraction. {S1P, N} and {RP, N} are allowed to overlap + provided RP <= S1P. + + This is a low-level function that is a building block for general + multiplication and division as well as other operations in GMP. It + is written in assembly for most CPUs. + + -- Function: void mpn_tdiv_qr (mp_limb_t *QP, mp_limb_t *RP, mp_size_t + QXN, const mp_limb_t *NP, mp_size_t NN, const mp_limb_t *DP, + mp_size_t DN) + Divide {NP, NN} by {DP, DN} and put the quotient at {QP, NN-DN+1} + and the remainder at {RP, DN}. The quotient is rounded towards 0. + + No overlap is permitted between arguments, except that NP might + equal RP. The dividend size NN must be greater than or equal to + divisor size DN. The most significant limb of the divisor must be + non-zero. The QXN operand must be zero. + + -- Function: mp_limb_t mpn_divrem (mp_limb_t *R1P, mp_size_t QXN, + mp_limb_t *RS2P, mp_size_t RS2N, const mp_limb_t *S3P, + mp_size_t S3N) + [This function is obsolete. Please call 'mpn_tdiv_qr' instead for + best performance.] + + Divide {RS2P, RS2N} by {S3P, S3N}, and write the quotient at R1P, + with the exception of the most significant limb, which is returned. + The remainder replaces the dividend at RS2P; it will be S3N limbs + long (i.e., as many limbs as the divisor). + + In addition to an integer quotient, QXN fraction limbs are + developed, and stored after the integral limbs. For most usages, + QXN will be zero. + + It is required that RS2N is greater than or equal to S3N. It is + required that the most significant bit of the divisor is set. + + If the quotient is not needed, pass RS2P + S3N as R1P. Aside from + that special case, no overlap between arguments is permitted. + + Return the most significant limb of the quotient, either 0 or 1. + + The area at R1P needs to be RS2N - S3N + QXN limbs large. + + -- Function: mp_limb_t mpn_divrem_1 (mp_limb_t *R1P, mp_size_t QXN, + mp_limb_t *S2P, mp_size_t S2N, mp_limb_t S3LIMB) + -- Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *R1P, mp_limb_t *S2P, + mp_size_t S2N, mp_limb_t S3LIMB) + Divide {S2P, S2N} by S3LIMB, and write the quotient at R1P. Return + the remainder. + + The integer quotient is written to {R1P+QXN, S2N} and in addition + QXN fraction limbs are developed and written to {R1P, QXN}. Either + or both S2N and QXN can be zero. For most usages, QXN will be + zero. + + 'mpn_divmod_1' exists for upward source compatibility and is simply + a macro calling 'mpn_divrem_1' with a QXN of 0. + + The areas at R1P and S2P have to be identical or completely + separate, not partially overlapping. + + -- Function: mp_limb_t mpn_divmod (mp_limb_t *R1P, mp_limb_t *RS2P, + mp_size_t RS2N, const mp_limb_t *S3P, mp_size_t S3N) + [This function is obsolete. Please call 'mpn_tdiv_qr' instead for + best performance.] + + -- Function: void mpn_divexact_1 (mp_limb_t * RP, const mp_limb_t * SP, + mp_size_t N, mp_limb_t D) + Divide {SP, N} by D, expecting it to divide exactly, and writing + the result to {RP, N}. If D doesn't divide exactly, the value + written to {RP, N} is undefined. The areas at RP and SP have to be + identical or completely separate, not partially overlapping. + + -- Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *RP, mp_limb_t *SP, + mp_size_t N) + -- Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *RP, mp_limb_t *SP, + mp_size_t N, mp_limb_t CARRY) + Divide {SP, N} by 3, expecting it to divide exactly, and writing + the result to {RP, N}. If 3 divides exactly, the return value is + zero and the result is the quotient. If not, the return value is + non-zero and the result won't be anything useful. + + 'mpn_divexact_by3c' takes an initial carry parameter, which can be + the return value from a previous call, so a large calculation can + be done piece by piece from low to high. 'mpn_divexact_by3' is + simply a macro calling 'mpn_divexact_by3c' with a 0 carry + parameter. + + These routines use a multiply-by-inverse and will be faster than + 'mpn_divrem_1' on CPUs with fast multiplication but slow division. + + The source a, result q, size n, initial carry i, and return value c + satisfy c*b^n + a-i = 3*q, where b=2^GMP_NUMB_BITS. The return c is + always 0, 1 or 2, and the initial carry i must also be 0, 1 or 2 + (these are both borrows really). When c=0 clearly q=(a-i)/3. When + c!=0, the remainder (a-i) mod 3 is given by 3-c, because b == 1 mod + 3 (when 'mp_bits_per_limb' is even, which is always so currently). + + -- Function: mp_limb_t mpn_mod_1 (const mp_limb_t *S1P, mp_size_t S1N, + mp_limb_t S2LIMB) + Divide {S1P, S1N} by S2LIMB, and return the remainder. S1N can be + zero. + + -- Function: mp_limb_t mpn_lshift (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N, unsigned int COUNT) + Shift {SP, N} left by COUNT bits, and write the result to {RP, N}. + The bits shifted out at the left are returned in the least + significant COUNT bits of the return value (the rest of the return + value is zero). + + COUNT must be in the range 1 to mp_bits_per_limb{}-1. The regions + {SP, N} and {RP, N} may overlap, provided RP >= SP. + + This function is written in assembly for most CPUs. + + -- Function: mp_limb_t mpn_rshift (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N, unsigned int COUNT) + Shift {SP, N} right by COUNT bits, and write the result to {RP, N}. + The bits shifted out at the right are returned in the most + significant COUNT bits of the return value (the rest of the return + value is zero). + + COUNT must be in the range 1 to mp_bits_per_limb{}-1. The regions + {SP, N} and {RP, N} may overlap, provided RP <= SP. + + This function is written in assembly for most CPUs. + + -- Function: int mpn_cmp (const mp_limb_t *S1P, const mp_limb_t *S2P, + mp_size_t N) + Compare {S1P, N} and {S2P, N} and return a positive value if S1 > + S2, 0 if they are equal, or a negative value if S1 < S2. + + -- Function: int mpn_zero_p (const mp_limb_t *SP, mp_size_t N) + Test {SP, N} and return 1 if the operand is zero, 0 otherwise. + + -- Function: mp_size_t mpn_gcd (mp_limb_t *RP, mp_limb_t *XP, mp_size_t + XN, mp_limb_t *YP, mp_size_t YN) + Set {RP, RETVAL} to the greatest common divisor of {XP, XN} and + {YP, YN}. The result can be up to YN limbs, the return value is + the actual number produced. Both source operands are destroyed. + + It is required that XN >= YN > 0, the most significant limb of {YP, + YN} must be non-zero, and at least one of the two operands must be + odd. No overlap is permitted between {XP, XN} and {YP, YN}. + + -- Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *XP, mp_size_t XN, + mp_limb_t YLIMB) + Return the greatest common divisor of {XP, XN} and YLIMB. Both + operands must be non-zero. + + -- Function: mp_size_t mpn_gcdext (mp_limb_t *GP, mp_limb_t *SP, + mp_size_t *SN, mp_limb_t *UP, mp_size_t UN, mp_limb_t *VP, + mp_size_t VN) + Let U be defined by {UP, UN} and let V be defined by {VP, VN}. + + Compute the greatest common divisor G of U and V. Compute a + cofactor S such that G = US + VT. The second cofactor T is not + computed but can easily be obtained from (G - U*S) / V (the + division will be exact). It is required that UN >= VN > 0, and the + most significant limb of {VP, VN} must be non-zero. + + S satisfies S = 1 or abs(S) < V / (2 G). S = 0 if and only if V + divides U (i.e., G = V). + + Store G at GP and let the return value define its limb count. + Store S at SP and let |*SN| define its limb count. S can be + negative; when this happens *SN will be negative. The area at GP + should have room for VN limbs and the area at SP should have room + for VN+1 limbs. + + Both source operands are destroyed. + + Compatibility notes: GMP 4.3.0 and 4.3.1 defined S less strictly. + Earlier as well as later GMP releases define S as described here. + GMP releases before GMP 4.3.0 required additional space for both + input and output areas. More precisely, the areas {UP, UN+1} and + {VP, VN+1} were destroyed (i.e. the operands plus an extra limb + past the end of each), and the areas pointed to by GP and SP should + each have room for UN+1 limbs. + + -- Function: mp_size_t mpn_sqrtrem (mp_limb_t *R1P, mp_limb_t *R2P, + const mp_limb_t *SP, mp_size_t N) + Compute the square root of {SP, N} and put the result at {R1P, + ceil(N/2)} and the remainder at {R2P, RETVAL}. R2P needs space for + N limbs, but the return value indicates how many are produced. + + The most significant limb of {SP, N} must be non-zero. The areas + {R1P, ceil(N/2)} and {SP, N} must be completely separate. The + areas {R2P, N} and {SP, N} must be either identical or completely + separate. + + If the remainder is not wanted then R2P can be 'NULL', and in this + case the return value is zero or non-zero according to whether the + remainder would have been zero or non-zero. + + A return value of zero indicates a perfect square. See also + 'mpn_perfect_square_p'. + + -- Function: size_t mpn_sizeinbase (const mp_limb_t *XP, mp_size_t N, + int BASE) + Return the size of {XP,N} measured in number of digits in the given + BASE. BASE can vary from 2 to 62. Requires N > 0 and XP[N-1] > 0. + The result will be either exact or 1 too big. If BASE is a power + of 2, the result is always exact. + + -- Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE, + mp_limb_t *S1P, mp_size_t S1N) + Convert {S1P, S1N} to a raw unsigned char array at STR in base + BASE, and return the number of characters produced. There may be + leading zeros in the string. The string is not in ASCII; to + convert it to printable format, add the ASCII codes for '0' or 'A', + depending on the base and range. BASE can vary from 2 to 256. + + The most significant limb of the input {S1P, S1N} must be non-zero. + The input {S1P, S1N} is clobbered, except when BASE is a power of + 2, in which case it's unchanged. + + The area at STR has to have space for the largest possible number + represented by a S1N long limb array, plus one extra character. + + -- Function: mp_size_t mpn_set_str (mp_limb_t *RP, const unsigned char + *STR, size_t STRSIZE, int BASE) + Convert bytes {STR,STRSIZE} in the given BASE to limbs at RP. + + STR[0] is the most significant input byte and STR[STRSIZE-1] is the + least significant input byte. Each byte should be a value in the + range 0 to BASE-1, not an ASCII character. BASE can vary from 2 to + 256. + + The converted value is {RP,RN} where RN is the return value. If + the most significant input byte STR[0] is non-zero, then RP[RN-1] + will be non-zero, else RP[RN-1] and some number of subsequent limbs + may be zero. + + The area at RP has to have space for the largest possible number + with STRSIZE digits in the chosen base, plus one extra limb. + + The input must have at least one byte, and no overlap is permitted + between {STR,STRSIZE} and the result at RP. + + -- Function: mp_bitcnt_t mpn_scan0 (const mp_limb_t *S1P, mp_bitcnt_t + BIT) + Scan S1P from bit position BIT for the next clear bit. + + It is required that there be a clear bit within the area at S1P at + or beyond bit position BIT, so that the function has something to + return. + + -- Function: mp_bitcnt_t mpn_scan1 (const mp_limb_t *S1P, mp_bitcnt_t + BIT) + Scan S1P from bit position BIT for the next set bit. + + It is required that there be a set bit within the area at S1P at or + beyond bit position BIT, so that the function has something to + return. + + -- Function: void mpn_random (mp_limb_t *R1P, mp_size_t R1N) + -- Function: void mpn_random2 (mp_limb_t *R1P, mp_size_t R1N) + Generate a random number of length R1N and store it at R1P. The + most significant limb is always non-zero. 'mpn_random' generates + uniformly distributed limb data, 'mpn_random2' generates long + strings of zeros and ones in the binary representation. + + 'mpn_random2' is intended for testing the correctness of the 'mpn' + routines. + + -- Function: mp_bitcnt_t mpn_popcount (const mp_limb_t *S1P, mp_size_t + N) + Count the number of set bits in {S1P, N}. + + -- Function: mp_bitcnt_t mpn_hamdist (const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Compute the hamming distance between {S1P, N} and {S2P, N}, which + is the number of bit positions where the two operands have + different bit values. + + -- Function: int mpn_perfect_square_p (const mp_limb_t *S1P, mp_size_t + N) + Return non-zero iff {S1P, N} is a perfect square. The most + significant limb of the input {S1P, N} must be non-zero. + + -- Function: void mpn_and_n (mp_limb_t *RP, const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical and of {S1P, N} and {S2P, N}, and write + the result to {RP, N}. + + -- Function: void mpn_ior_n (mp_limb_t *RP, const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical inclusive or of {S1P, N} and {S2P, N}, + and write the result to {RP, N}. + + -- Function: void mpn_xor_n (mp_limb_t *RP, const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical exclusive or of {S1P, N} and {S2P, N}, + and write the result to {RP, N}. + + -- Function: void mpn_andn_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical and of {S1P, N} and the bitwise + complement of {S2P, N}, and write the result to {RP, N}. + + -- Function: void mpn_iorn_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical inclusive or of {S1P, N} and the + bitwise complement of {S2P, N}, and write the result to {RP, N}. + + -- Function: void mpn_nand_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical and of {S1P, N} and {S2P, N}, and write + the bitwise complement of the result to {RP, N}. + + -- Function: void mpn_nior_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical inclusive or of {S1P, N} and {S2P, N}, + and write the bitwise complement of the result to {RP, N}. + + -- Function: void mpn_xnor_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Perform the bitwise logical exclusive or of {S1P, N} and {S2P, N}, + and write the bitwise complement of the result to {RP, N}. + + -- Function: void mpn_com (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N) + Perform the bitwise complement of {SP, N}, and write the result to + {RP, N}. + + -- Function: void mpn_copyi (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N) + Copy from {S1P, N} to {RP, N}, increasingly. + + -- Function: void mpn_copyd (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N) + Copy from {S1P, N} to {RP, N}, decreasingly. + + -- Function: void mpn_zero (mp_limb_t *RP, mp_size_t N) + Zero {RP, N}. + + +8.1 Low-level functions for cryptography +======================================== + +The functions prefixed with 'mpn_sec_' and 'mpn_cnd_' are designed to +perform the exact same low-level operations and have the same cache +access patterns for any two same-size arguments, assuming that function +arguments are placed at the same position and that the machine state is +identical upon function entry. These functions are intended for +cryptographic purposes, where resilience to side-channel attacks is +desired. + + These functions are less efficient than their "leaky" counterparts; +their performance for operands of the sizes typically used for +cryptographic applications is between 15% and 100% worse. For larger +operands, these functions might be inadequate, since they rely on +asymptotically elementary algorithms. + + These functions do not make any explicit allocations. Those of these +functions that need scratch space accept a scratch space operand. This +convention allows callers to keep sensitive data in designated memory +areas. Note however that compilers may choose to spill scalar values +used within these functions to their stack frame and that such scalars +may contain sensitive data. + + In addition to these specially crafted functions, the following 'mpn' +functions are naturally side-channel resistant: 'mpn_add_n', +'mpn_sub_n', 'mpn_lshift', 'mpn_rshift', 'mpn_zero', 'mpn_copyi', +'mpn_copyd', 'mpn_com', and the logical function ('mpn_and_n', etc). + + There are some exceptions from the side-channel resilience: (1) Some +assembly implementations of 'mpn_lshift' identify shift-by-one as a +special case. This is a problem iff the shift count is a function of +sensitive data. (2) Alpha ev6 and Pentium4 using 64-bit limbs have +leaky 'mpn_add_n' and 'mpn_sub_n'. (3) Alpha ev6 has a leaky +'mpn_mul_1' which also makes 'mpn_sec_mul' on those systems unsafe. + + -- Function: mp_limb_t mpn_cnd_add_n (mp_limb_t CND, mp_limb_t *RP, + const mp_limb_t *S1P, const mp_limb_t *S2P, mp_size_t N) + -- Function: mp_limb_t mpn_cnd_sub_n (mp_limb_t CND, mp_limb_t *RP, + const mp_limb_t *S1P, const mp_limb_t *S2P, mp_size_t N) + These functions do conditional addition and subtraction. If CND is + non-zero, they produce the same result as a regular 'mpn_add_n' or + 'mpn_sub_n', and if CND is zero, they copy {S1P,N} to the result + area and return zero. The functions are designed to have timing + and memory access patterns depending only on size and location of + the data areas, but independent of the condition CND. Like for + 'mpn_add_n' and 'mpn_sub_n', on most machines, the timing will also + be independent of the actual limb values. + + -- Function: mp_limb_t mpn_sec_add_1 (mp_limb_t *RP, const mp_limb_t + *AP, mp_size_t N, mp_limb_t B, mp_limb_t *TP) + -- Function: mp_limb_t mpn_sec_sub_1 (mp_limb_t *RP, const mp_limb_t + *AP, mp_size_t N, mp_limb_t B, mp_limb_t *TP) + Set R to A + B or A - B, respectively, where R = {RP,N}, A = + {AP,N}, and B is a single limb. Returns carry. + + These functions take O(N) time, unlike the leaky functions + 'mpn_add_1' which are O(1) on average. They require scratch space + of 'mpn_sec_add_1_itch(N)' and 'mpn_sec_sub_1_itch(N)' limbs, + respectively, to be passed in the TP parameter. The scratch space + requirements are guaranteed to be at most N limbs, and increase + monotonously in the operand size. + + -- Function: void mpn_cnd_swap (mp_limb_t CND, volatile mp_limb_t *AP, + volatile mp_limb_t *BP, mp_size_t N) + If CND is non-zero, swaps the contents of the areas {AP,N} and + {BP,N}. Otherwise, the areas are left unmodified. Implemented + using logical operations on the limbs, with the same memory + accesses independent of the value of CND. + + -- Function: void mpn_sec_mul (mp_limb_t *RP, const mp_limb_t *AP, + mp_size_t AN, const mp_limb_t *BP, mp_size_t BN, mp_limb_t + *TP) + -- Function: mp_size_t mpn_sec_mul_itch (mp_size_t AN, mp_size_t BN) + Set R to A * B, where A = {AP,AN}, B = {BP,BN}, and R = {RP,AN+BN}. + + It is required that AN >= BN > 0. + + No overlapping between R and the input operands is allowed. For A + = B, use 'mpn_sec_sqr' for optimal performance. + + This function requires scratch space of 'mpn_sec_mul_itch(AN, BN)' + limbs to be passed in the TP parameter. The scratch space + requirements are guaranteed to increase monotonously in the operand + sizes. + + -- Function: void mpn_sec_sqr (mp_limb_t *RP, const mp_limb_t *AP, + mp_size_t AN, mp_limb_t *TP) + -- Function: mp_size_t mpn_sec_sqr_itch (mp_size_t AN) + Set R to A^2, where A = {AP,AN}, and R = {RP,2AN}. + + It is required that AN > 0. + + No overlapping between R and the input operands is allowed. + + This function requires scratch space of 'mpn_sec_sqr_itch(AN)' + limbs to be passed in the TP parameter. The scratch space + requirements are guaranteed to increase monotonously in the operand + size. + + -- Function: void mpn_sec_powm (mp_limb_t *RP, const mp_limb_t *BP, + mp_size_t BN, const mp_limb_t *EP, mp_bitcnt_t ENB, const + mp_limb_t *MP, mp_size_t N, mp_limb_t *TP) + -- Function: mp_size_t mpn_sec_powm_itch (mp_size_t BN, mp_bitcnt_t + ENB, size_t N) + Set R to (B raised to E) modulo M, where R = {RP,N}, M = {MP,N}, + and E = {EP,ceil(ENB / 'GMP\_NUMB\_BITS')}. + + It is required that B > 0, that M > 0 is odd, and that E < 2^ENB, + with ENB > 0. + + No overlapping between R and the input operands is allowed. + + This function requires scratch space of 'mpn_sec_powm_itch(BN, ENB, + N)' limbs to be passed in the TP parameter. The scratch space + requirements are guaranteed to increase monotonously in the operand + sizes. + + -- Function: void mpn_sec_tabselect (mp_limb_t *RP, const mp_limb_t + *TAB, mp_size_t N, mp_size_t NENTS, mp_size_t WHICH) + Select entry WHICH from table TAB, which has NENTS entries, each N + limbs. Store the selected entry at RP. + + This function reads the entire table to avoid side-channel + information leaks. + + -- Function: mp_limb_t mpn_sec_div_qr (mp_limb_t *QP, mp_limb_t *NP, + mp_size_t NN, const mp_limb_t *DP, mp_size_t DN, mp_limb_t + *TP) + -- Function: mp_size_t mpn_sec_div_qr_itch (mp_size_t NN, mp_size_t DN) + + Set Q to the truncated quotient N / D and R to N modulo D, where N + = {NP,NN}, D = {DP,DN}, Q's most significant limb is the function + return value and the remaining limbs are {QP,NN-DN}, and R = + {NP,DN}. + + It is required that NN >= DN >= 1, and that DP[DN-1] != 0. This + does not imply that N >= D since N might be zero-padded. + + Note the overlapping between N and R. No other operand overlapping + is allowed. The entire space occupied by N is overwritten. + + This function requires scratch space of 'mpn_sec_div_qr_itch(NN, + DN)' limbs to be passed in the TP parameter. + + -- Function: void mpn_sec_div_r (mp_limb_t *NP, mp_size_t NN, const + mp_limb_t *DP, mp_size_t DN, mp_limb_t *TP) + -- Function: mp_size_t mpn_sec_div_r_itch (mp_size_t NN, mp_size_t DN) + + Set R to N modulo D, where N = {NP,NN}, D = {DP,DN}, and R = + {NP,DN}. + + It is required that NN >= DN >= 1, and that DP[DN-1] != 0. This + does not imply that N >= D since N might be zero-padded. + + Note the overlapping between N and R. No other operand overlapping + is allowed. The entire space occupied by N is overwritten. + + This function requires scratch space of 'mpn_sec_div_r_itch(NN, + DN)' limbs to be passed in the TP parameter. + + -- Function: int mpn_sec_invert (mp_limb_t *RP, mp_limb_t *AP, const + mp_limb_t *MP, mp_size_t N, mp_bitcnt_t NBCNT, mp_limb_t *TP) + -- Function: mp_size_t mpn_sec_invert_itch (mp_size_t N) + Set R to the inverse of A modulo M, where R = {RP,N}, A = {AP,N}, + and M = {MP,N}. *This function's interface is preliminary.* + + If an inverse exists, return 1, otherwise return 0 and leave R + undefined. In either case, the input A is destroyed. + + It is required that M is odd, and that NBCNT >= ceil(\log(A+1)) + + ceil(\log(M+1)). A safe choice is NBCNT = 2 * N * GMP_NUMB_BITS, + but a smaller value might improve performance if M or A are known + to have leading zero bits. + + This function requires scratch space of 'mpn_sec_invert_itch(N)' + limbs to be passed in the TP parameter. + + +8.2 Nails +========= + +*Everything in this section is highly experimental and may disappear or +be subject to incompatible changes in a future version of GMP.* + + Nails are an experimental feature whereby a few bits are left unused +at the top of each 'mp_limb_t'. This can significantly improve carry +handling on some processors. + + All the 'mpn' functions accepting limb data will expect the nail bits +to be zero on entry, and will return data with the nails similarly all +zero. This applies both to limb vectors and to single limb arguments. + + Nails can be enabled by configuring with '--enable-nails'. By +default the number of bits will be chosen according to what suits the +host processor, but a particular number can be selected with +'--enable-nails=N'. + + At the mpn level, a nail build is neither source nor binary +compatible with a non-nail build, strictly speaking. But programs +acting on limbs only through the mpn functions are likely to work +equally well with either build, and judicious use of the definitions +below should make any program compatible with either build, at the +source level. + + For the higher level routines, meaning 'mpz' etc, a nail build should +be fully source and binary compatible with a non-nail build. + + -- Macro: GMP_NAIL_BITS + -- Macro: GMP_NUMB_BITS + -- Macro: GMP_LIMB_BITS + 'GMP_NAIL_BITS' is the number of nail bits, or 0 when nails are not + in use. 'GMP_NUMB_BITS' is the number of data bits in a limb. + 'GMP_LIMB_BITS' is the total number of bits in an 'mp_limb_t'. In + all cases + + GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS + + -- Macro: GMP_NAIL_MASK + -- Macro: GMP_NUMB_MASK + Bit masks for the nail and number parts of a limb. 'GMP_NAIL_MASK' + is 0 when nails are not in use. + + 'GMP_NAIL_MASK' is not often needed, since the nail part can be + obtained with 'x >> GMP_NUMB_BITS', and that means one less large + constant, which can help various RISC chips. + + -- Macro: GMP_NUMB_MAX + The maximum value that can be stored in the number part of a limb. + This is the same as 'GMP_NUMB_MASK', but can be used for clarity + when doing comparisons rather than bit-wise operations. + + The term "nails" comes from finger or toe nails, which are at the +ends of a limb (arm or leg). "numb" is short for number, but is also +how the developers felt after trying for a long time to come up with +sensible names for these things. + + In the future (the distant future most likely) a non-zero nail might +be permitted, giving non-unique representations for numbers in a limb +vector. This would help vector processors since carries would only ever +need to propagate one or two limbs. + + +File: gmp.info, Node: Random Number Functions, Next: Formatted Output, Prev: Low-level Functions, Up: Top + +9 Random Number Functions +************************* + +Sequences of pseudo-random numbers in GMP are generated using a variable +of type 'gmp_randstate_t', which holds an algorithm selection and a +current state. Such a variable must be initialized by a call to one of +the 'gmp_randinit' functions, and can be seeded with one of the +'gmp_randseed' functions. + + The functions actually generating random numbers are described in +*note Integer Random Numbers::, and *note Miscellaneous Float +Functions::. + + The older style random number functions don't accept a +'gmp_randstate_t' parameter but instead share a global variable of that +type. They use a default algorithm and are currently not seeded (though +perhaps that will change in the future). The new functions accepting a +'gmp_randstate_t' are recommended for applications that care about +randomness. + +* Menu: + +* Random State Initialization:: +* Random State Seeding:: +* Random State Miscellaneous:: + + +File: gmp.info, Node: Random State Initialization, Next: Random State Seeding, Prev: Random Number Functions, Up: Random Number Functions + +9.1 Random State Initialization +=============================== + + -- Function: void gmp_randinit_default (gmp_randstate_t STATE) + Initialize STATE with a default algorithm. This will be a + compromise between speed and randomness, and is recommended for + applications with no special requirements. Currently this is + 'gmp_randinit_mt'. + + -- Function: void gmp_randinit_mt (gmp_randstate_t STATE) + Initialize STATE for a Mersenne Twister algorithm. This algorithm + is fast and has good randomness properties. + + -- Function: void gmp_randinit_lc_2exp (gmp_randstate_t STATE, const + mpz_t A, unsigned long C, mp_bitcnt_t M2EXP) + Initialize STATE with a linear congruential algorithm X = (A*X + C) + mod 2^M2EXP. + + The low bits of X in this algorithm are not very random. The least + significant bit will have a period no more than 2, and the second + bit no more than 4, etc. For this reason only the high half of + each X is actually used. + + When a random number of more than M2EXP/2 bits is to be generated, + multiple iterations of the recurrence are used and the results + concatenated. + + -- Function: int gmp_randinit_lc_2exp_size (gmp_randstate_t STATE, + mp_bitcnt_t SIZE) + Initialize STATE for a linear congruential algorithm as per + 'gmp_randinit_lc_2exp'. A, C and M2EXP are selected from a table, + chosen so that SIZE bits (or more) of each X will be used, i.e. + M2EXP/2 >= SIZE. + + If successful the return value is non-zero. If SIZE is bigger than + the table data provides then the return value is zero. The maximum + SIZE currently supported is 128. + + -- Function: void gmp_randinit_set (gmp_randstate_t ROP, + gmp_randstate_t OP) + Initialize ROP with a copy of the algorithm and state from OP. + + -- Function: void gmp_randinit (gmp_randstate_t STATE, + gmp_randalg_t ALG, ...) + *This function is obsolete.* + + Initialize STATE with an algorithm selected by ALG. The only + choice is 'GMP_RAND_ALG_LC', which is 'gmp_randinit_lc_2exp_size' + described above. A third parameter of type 'unsigned long' is + required, this is the SIZE for that function. + 'GMP_RAND_ALG_DEFAULT' and 0 are the same as 'GMP_RAND_ALG_LC'. + + 'gmp_randinit' sets bits in the global variable 'gmp_errno' to + indicate an error. 'GMP_ERROR_UNSUPPORTED_ARGUMENT' if ALG is + unsupported, or 'GMP_ERROR_INVALID_ARGUMENT' if the SIZE parameter + is too big. It may be noted this error reporting is not thread + safe (a good reason to use 'gmp_randinit_lc_2exp_size' instead). + + -- Function: void gmp_randclear (gmp_randstate_t STATE) + Free all memory occupied by STATE. + + +File: gmp.info, Node: Random State Seeding, Next: Random State Miscellaneous, Prev: Random State Initialization, Up: Random Number Functions + +9.2 Random State Seeding +======================== + + -- Function: void gmp_randseed (gmp_randstate_t STATE, const mpz_t + SEED) + -- Function: void gmp_randseed_ui (gmp_randstate_t STATE, + unsigned long int SEED) + Set an initial seed value into STATE. + + The size of a seed determines how many different sequences of + random numbers it's possible to generate. The "quality" of the + seed is the randomness of a given seed compared to the previous + seed used, and this affects the randomness of separate number + sequences. The method for choosing a seed is critical if the + generated numbers are to be used for important applications, such + as generating cryptographic keys. + + Traditionally the system time has been used to seed, but care needs + to be taken with this. If an application seeds often and the + resolution of the system clock is low, then the same sequence of + numbers might be repeated. Also, the system time is quite easy to + guess, so if unpredictability is required then it should definitely + not be the only source for the seed value. On some systems there's + a special device '/dev/random' which provides random data better + suited for use as a seed. + + +File: gmp.info, Node: Random State Miscellaneous, Prev: Random State Seeding, Up: Random Number Functions + +9.3 Random State Miscellaneous +============================== + + -- Function: unsigned long gmp_urandomb_ui (gmp_randstate_t STATE, + unsigned long N) + Return a uniformly distributed random number of N bits, i.e. in the + range 0 to 2^N-1 inclusive. N must be less than or equal to the + number of bits in an 'unsigned long'. + + -- Function: unsigned long gmp_urandomm_ui (gmp_randstate_t STATE, + unsigned long N) + Return a uniformly distributed random number in the range 0 to N-1, + inclusive. + + +File: gmp.info, Node: Formatted Output, Next: Formatted Input, Prev: Random Number Functions, Up: Top + +10 Formatted Output +******************* + +* Menu: + +* Formatted Output Strings:: +* Formatted Output Functions:: +* C++ Formatted Output:: + + +File: gmp.info, Node: Formatted Output Strings, Next: Formatted Output Functions, Prev: Formatted Output, Up: Formatted Output + +10.1 Format Strings +=================== + +'gmp_printf' and friends accept format strings similar to the standard C +'printf' (*note Formatted Output: (libc)Formatted Output.). A format +specification is of the form + + % [flags] [width] [.[precision]] [type] conv + + GMP adds types 'Z', 'Q' and 'F' for 'mpz_t', 'mpq_t' and 'mpf_t' +respectively, 'M' for 'mp_limb_t', and 'N' for an 'mp_limb_t' array. +'Z', 'Q', 'M' and 'N' behave like integers. 'Q' will print a '/' and a +denominator, if needed. 'F' behaves like a float. For example, + + mpz_t z; + gmp_printf ("%s is an mpz %Zd\n", "here", z); + + mpq_t q; + gmp_printf ("a hex rational: %#40Qx\n", q); + + mpf_t f; + int n; + gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n); + + mp_limb_t l; + gmp_printf ("limb %Mu\n", l); + + const mp_limb_t *ptr; + mp_size_t size; + gmp_printf ("limb array %Nx\n", ptr, size); + + For 'N' the limbs are expected least significant first, as per the +'mpn' functions (*note Low-level Functions::). A negative size can be +given to print the value as a negative. + + All the standard C 'printf' types behave the same as the C library +'printf', and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are +simply handed to 'printf' and only the GMP extensions handled directly. + + The flags accepted are as follows. GLIBC style ' is only for the +standard C types (not the GMP types), and only if the C library supports +it. + + 0 pad with zeros (rather than spaces) + # show the base with '0x', '0X' or '0' + + always show a sign + (space) show a space or a '-' sign + ' group digits, GLIBC style (not GMP + types) + + The optional width and precision can be given as a number within the +format string, or as a '*' to take an extra parameter of type 'int', the +same as the standard 'printf'. + + The standard types accepted are as follows. 'h' and 'l' are +portable, the rest will depend on the compiler (or include files) for +the type and the C library for the output. + + h short + hh char + j intmax_t or uintmax_t + l long or wchar_t + ll long long + L long double + q quad_t or u_quad_t + t ptrdiff_t + z size_t + +The GMP types are + + F mpf_t, float conversions + Q mpq_t, integer conversions + M mp_limb_t, integer conversions + N mp_limb_t array, integer conversions + Z mpz_t, integer conversions + + The conversions accepted are as follows. 'a' and 'A' are always +supported for 'mpf_t' but depend on the C library for standard C float +types. 'm' and 'p' depend on the C library. + + a A hex floats, C99 style + c character + d decimal integer + e E scientific format float + f fixed point float + i same as d + g G fixed or scientific float + m 'strerror' string, GLIBC style + n store characters written so far + o octal integer + p pointer + s string + u unsigned integer + x X hex integer + + 'o', 'x' and 'X' are unsigned for the standard C types, but for types +'Z', 'Q' and 'N' they are signed. 'u' is not meaningful for 'Z', 'Q' +and 'N'. + + 'M' is a proxy for the C library 'l' or 'L', according to the size of +'mp_limb_t'. Unsigned conversions will be usual, but a signed +conversion can be used and will interpret the value as a two's +complement negative. + + 'n' can be used with any type, even the GMP types. + + Other types or conversions that might be accepted by the C library +'printf' cannot be used through 'gmp_printf', this includes for instance +extensions registered with GLIBC 'register_printf_function'. Also +currently there's no support for POSIX '$' style numbered arguments +(perhaps this will be added in the future). + + The precision field has its usual meaning for integer 'Z' and float +'F' types, but is currently undefined for 'Q' and should not be used +with that. + + 'mpf_t' conversions only ever generate as many digits as can be +accurately represented by the operand, the same as 'mpf_get_str' does. +Zeros will be used if necessary to pad to the requested precision. This +happens even for an 'f' conversion of an 'mpf_t' which is an integer, +for instance 2^1024 in an 'mpf_t' of 128 bits precision will only +produce about 40 digits, then pad with zeros to the decimal point. An +empty precision field like '%.Fe' or '%.Ff' can be used to specifically +request just the significant digits. Without any dot and thus no +precision field, a precision value of 6 will be used. Note that these +rules mean that '%Ff', '%.Ff', and '%.0Ff' will all be different. + + The decimal point character (or string) is taken from the current +locale settings on systems which provide 'localeconv' (*note Locales and +Internationalization: (libc)Locales.). The C library will normally do +the same for standard float output. + + The format string is only interpreted as plain 'char's, multibyte +characters are not recognised. Perhaps this will change in the future. + + +File: gmp.info, Node: Formatted Output Functions, Next: C++ Formatted Output, Prev: Formatted Output Strings, Up: Formatted Output + +10.2 Functions +============== + +Each of the following functions is similar to the corresponding C +library function. The basic 'printf' forms take a variable argument +list. The 'vprintf' forms take an argument pointer, see *note Variadic +Functions: (libc)Variadic Functions, or 'man 3 va_start'. + + It should be emphasised that if a format string is invalid, or the +arguments don't match what the format specifies, then the behaviour of +any of these functions will be unpredictable. GCC format string +checking is not available, since it doesn't recognise the GMP +extensions. + + The file based functions 'gmp_printf' and 'gmp_fprintf' will return +-1 to indicate a write error. Output is not "atomic", so partial output +may be produced if a write error occurs. All the functions can return +-1 if the C library 'printf' variant in use returns -1, but this +shouldn't normally occur. + + -- Function: int gmp_printf (const char *FMT, ...) + -- Function: int gmp_vprintf (const char *FMT, va_list AP) + Print to the standard output 'stdout'. Return the number of + characters written, or -1 if an error occurred. + + -- Function: int gmp_fprintf (FILE *FP, const char *FMT, ...) + -- Function: int gmp_vfprintf (FILE *FP, const char *FMT, va_list AP) + Print to the stream FP. Return the number of characters written, + or -1 if an error occurred. + + -- Function: int gmp_sprintf (char *BUF, const char *FMT, ...) + -- Function: int gmp_vsprintf (char *BUF, const char *FMT, va_list AP) + Form a null-terminated string in BUF. Return the number of + characters written, excluding the terminating null. + + No overlap is permitted between the space at BUF and the string + FMT. + + These functions are not recommended, since there's no protection + against exceeding the space available at BUF. + + -- Function: int gmp_snprintf (char *BUF, size_t SIZE, const char *FMT, + ...) + -- Function: int gmp_vsnprintf (char *BUF, size_t SIZE, const char + *FMT, va_list AP) + Form a null-terminated string in BUF. No more than SIZE bytes will + be written. To get the full output, SIZE must be enough for the + string and null-terminator. + + The return value is the total number of characters which ought to + have been produced, excluding the terminating null. If RETVAL >= + SIZE then the actual output has been truncated to the first SIZE-1 + characters, and a null appended. + + No overlap is permitted between the region {BUF,SIZE} and the FMT + string. + + Notice the return value is in ISO C99 'snprintf' style. This is so + even if the C library 'vsnprintf' is the older GLIBC 2.0.x style. + + -- Function: int gmp_asprintf (char **PP, const char *FMT, ...) + -- Function: int gmp_vasprintf (char **PP, const char *FMT, va_list AP) + Form a null-terminated string in a block of memory obtained from + the current memory allocation function (*note Custom Allocation::). + The block will be the size of the string and null-terminator. The + address of the block is stored to *PP. The return value is the + number of characters produced, excluding the null-terminator. + + Unlike the C library 'asprintf', 'gmp_asprintf' doesn't return -1 + if there's no more memory available, it lets the current allocation + function handle that. + + -- Function: int gmp_obstack_printf (struct obstack *OB, const char + *FMT, ...) + -- Function: int gmp_obstack_vprintf (struct obstack *OB, const char + *FMT, va_list AP) + Append to the current object in OB. The return value is the number + of characters written. A null-terminator is not written. + + FMT cannot be within the current object in OB, since that object + might move as it grows. + + These functions are available only when the C library provides the + obstack feature, which probably means only on GNU systems, see + *note Obstacks: (libc)Obstacks. + + +File: gmp.info, Node: C++ Formatted Output, Prev: Formatted Output Functions, Up: Formatted Output + +10.3 C++ Formatted Output +========================= + +The following functions are provided in 'libgmpxx' (*note Headers and +Libraries::), which is built if C++ support is enabled (*note Build +Options::). Prototypes are available from ''. + + -- Function: ostream& operator<< (ostream& STREAM, const mpz_t OP) + Print OP to STREAM, using its 'ios' formatting settings. + 'ios::width' is reset to 0 after output, the same as the standard + 'ostream operator<<' routines do. + + In hex or octal, OP is printed as a signed number, the same as for + decimal. This is unlike the standard 'operator<<' routines on + 'int' etc, which instead give two's complement. + + -- Function: ostream& operator<< (ostream& STREAM, const mpq_t OP) + Print OP to STREAM, using its 'ios' formatting settings. + 'ios::width' is reset to 0 after output, the same as the standard + 'ostream operator<<' routines do. + + Output will be a fraction like '5/9', or if the denominator is 1 + then just a plain integer like '123'. + + In hex or octal, OP is printed as a signed value, the same as for + decimal. If 'ios::showbase' is set then a base indicator is shown + on both the numerator and denominator (if the denominator is + required). + + -- Function: ostream& operator<< (ostream& STREAM, const mpf_t OP) + Print OP to STREAM, using its 'ios' formatting settings. + 'ios::width' is reset to 0 after output, the same as the standard + 'ostream operator<<' routines do. + + The decimal point follows the standard library float 'operator<<', + which on recent systems means the 'std::locale' imbued on STREAM. + + Hex and octal are supported, unlike the standard 'operator<<' on + 'double'. The mantissa will be in hex or octal, the exponent will + be in decimal. For hex the exponent delimiter is an '@'. This is + as per 'mpf_out_str'. + + 'ios::showbase' is supported, and will put a base on the mantissa, + for example hex '0x1.8' or '0x0.8', or octal '01.4' or '00.4'. + This last form is slightly strange, but at least differentiates + itself from decimal. + + These operators mean that GMP types can be printed in the usual C++ +way, for example, + + mpz_t z; + int n; + ... + cout << "iteration " << n << " value " << z << "\n"; + + But note that 'ostream' output (and 'istream' input, *note C++ +Formatted Input::) is the only overloading available for the GMP types +and that for instance using '+' with an 'mpz_t' will have unpredictable +results. For classes with overloading, see *note C++ Class Interface::. + + +File: gmp.info, Node: Formatted Input, Next: C++ Class Interface, Prev: Formatted Output, Up: Top + +11 Formatted Input +****************** + +* Menu: + +* Formatted Input Strings:: +* Formatted Input Functions:: +* C++ Formatted Input:: + + +File: gmp.info, Node: Formatted Input Strings, Next: Formatted Input Functions, Prev: Formatted Input, Up: Formatted Input + +11.1 Formatted Input Strings +============================ + +'gmp_scanf' and friends accept format strings similar to the standard C +'scanf' (*note Formatted Input: (libc)Formatted Input.). A format +specification is of the form + + % [flags] [width] [type] conv + + GMP adds types 'Z', 'Q' and 'F' for 'mpz_t', 'mpq_t' and 'mpf_t' +respectively. 'Z' and 'Q' behave like integers. 'Q' will read a '/' +and a denominator, if present. 'F' behaves like a float. + + GMP variables don't require an '&' when passed to 'gmp_scanf', since +they're already "call-by-reference". For example, + + /* to read say "a(5) = 1234" */ + int n; + mpz_t z; + gmp_scanf ("a(%d) = %Zd\n", &n, z); + + mpq_t q1, q2; + gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2); + + /* to read say "topleft (1.55,-2.66)" */ + mpf_t x, y; + char buf[32]; + gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y); + + All the standard C 'scanf' types behave the same as in the C library +'scanf', and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are +simply handed to 'scanf' and only the GMP extensions handled directly. + + The flags accepted are as follows. 'a' and ''' will depend on +support from the C library, and ''' cannot be used with GMP types. + + * read but don't store + a allocate a buffer (string conversions) + ' grouped digits, GLIBC style (not GMP + types) + + The standard types accepted are as follows. 'h' and 'l' are +portable, the rest will depend on the compiler (or include files) for +the type and the C library for the input. + + h short + hh char + j intmax_t or uintmax_t + l long int, double or wchar_t + ll long long + L long double + q quad_t or u_quad_t + t ptrdiff_t + z size_t + +The GMP types are + + F mpf_t, float conversions + Q mpq_t, integer conversions + Z mpz_t, integer conversions + + The conversions accepted are as follows. 'p' and '[' will depend on +support from the C library, the rest are standard. + + c character or characters + d decimal integer + e E f g float + G + i integer with base indicator + n characters read so far + o octal integer + p pointer + s string of non-whitespace characters + u decimal integer + x X hex integer + [ string of characters in a set + + 'e', 'E', 'f', 'g' and 'G' are identical, they all read either fixed +point or scientific format, and either upper or lower case 'e' for the +exponent in scientific format. + + C99 style hex float format ('printf %a', *note Formatted Output +Strings::) is always accepted for 'mpf_t', but for the standard float +types it will depend on the C library. + + 'x' and 'X' are identical, both accept both upper and lower case +hexadecimal. + + 'o', 'u', 'x' and 'X' all read positive or negative values. For the +standard C types these are described as "unsigned" conversions, but that +merely affects certain overflow handling, negatives are still allowed +(per 'strtoul', *note Parsing of Integers: (libc)Parsing of Integers.). +For GMP types there are no overflows, so 'd' and 'u' are identical. + + 'Q' type reads the numerator and (optional) denominator as given. If +the value might not be in canonical form then 'mpq_canonicalize' must be +called before using it in any calculations (*note Rational Number +Functions::). + + 'Qi' will read a base specification separately for the numerator and +denominator. For example '0x10/11' would be 16/11, whereas '0x10/0x11' +would be 16/17. + + 'n' can be used with any of the types above, even the GMP types. '*' +to suppress assignment is allowed, though in that case it would do +nothing at all. + + Other conversions or types that might be accepted by the C library +'scanf' cannot be used through 'gmp_scanf'. + + Whitespace is read and discarded before a field, except for 'c' and +'[' conversions. + + For float conversions, the decimal point character (or string) +expected is taken from the current locale settings on systems which +provide 'localeconv' (*note Locales and Internationalization: +(libc)Locales.). The C library will normally do the same for standard +float input. + + The format string is only interpreted as plain 'char's, multibyte +characters are not recognised. Perhaps this will change in the future. + + +File: gmp.info, Node: Formatted Input Functions, Next: C++ Formatted Input, Prev: Formatted Input Strings, Up: Formatted Input + +11.2 Formatted Input Functions +============================== + +Each of the following functions is similar to the corresponding C +library function. The plain 'scanf' forms take a variable argument +list. The 'vscanf' forms take an argument pointer, see *note Variadic +Functions: (libc)Variadic Functions, or 'man 3 va_start'. + + It should be emphasised that if a format string is invalid, or the +arguments don't match what the format specifies, then the behaviour of +any of these functions will be unpredictable. GCC format string +checking is not available, since it doesn't recognise the GMP +extensions. + + No overlap is permitted between the FMT string and any of the results +produced. + + -- Function: int gmp_scanf (const char *FMT, ...) + -- Function: int gmp_vscanf (const char *FMT, va_list AP) + Read from the standard input 'stdin'. + + -- Function: int gmp_fscanf (FILE *FP, const char *FMT, ...) + -- Function: int gmp_vfscanf (FILE *FP, const char *FMT, va_list AP) + Read from the stream FP. + + -- Function: int gmp_sscanf (const char *S, const char *FMT, ...) + -- Function: int gmp_vsscanf (const char *S, const char *FMT, va_list + AP) + Read from a null-terminated string S. + + The return value from each of these functions is the same as the +standard C99 'scanf', namely the number of fields successfully parsed +and stored. '%n' fields and fields read but suppressed by '*' don't +count towards the return value. + + If end of input (or a file error) is reached before a character for a +field or a literal, and if no previous non-suppressed fields have +matched, then the return value is 'EOF' instead of 0. A whitespace +character in the format string is only an optional match and doesn't +induce an 'EOF' in this fashion. Leading whitespace read and discarded +for a field don't count as characters for that field. + + For the GMP types, input parsing follows C99 rules, namely one +character of lookahead is used and characters are read while they +continue to meet the format requirements. If this doesn't provide a +complete number then the function terminates, with that field not stored +nor counted towards the return value. For instance with 'mpf_t' an +input '1.23e-XYZ' would be read up to the 'X' and that character pushed +back since it's not a digit. The string '1.23e-' would then be +considered invalid since an 'e' must be followed by at least one digit. + + For the standard C types, in the current implementation GMP calls the +C library 'scanf' functions, which might have looser rules about what +constitutes a valid input. + + Note that 'gmp_sscanf' is the same as 'gmp_fscanf' and only does one +character of lookahead when parsing. Although clearly it could look at +its entire input, it is deliberately made identical to 'gmp_fscanf', the +same way C99 'sscanf' is the same as 'fscanf'. + + +File: gmp.info, Node: C++ Formatted Input, Prev: Formatted Input Functions, Up: Formatted Input + +11.3 C++ Formatted Input +======================== + +The following functions are provided in 'libgmpxx' (*note Headers and +Libraries::), which is built only if C++ support is enabled (*note Build +Options::). Prototypes are available from ''. + + -- Function: istream& operator>> (istream& STREAM, mpz_t ROP) + Read ROP from STREAM, using its 'ios' formatting settings. + + -- Function: istream& operator>> (istream& STREAM, mpq_t ROP) + An integer like '123' will be read, or a fraction like '5/9'. No + whitespace is allowed around the '/'. If the fraction is not in + canonical form then 'mpq_canonicalize' must be called (*note + Rational Number Functions::) before operating on it. + + As per integer input, an '0' or '0x' base indicator is read when + none of 'ios::dec', 'ios::oct' or 'ios::hex' are set. This is done + separately for numerator and denominator, so that for instance + '0x10/11' is 16/11 and '0x10/0x11' is 16/17. + + -- Function: istream& operator>> (istream& STREAM, mpf_t ROP) + Read ROP from STREAM, using its 'ios' formatting settings. + + Hex or octal floats are not supported, but might be in the future, + or perhaps it's best to accept only what the standard float + 'operator>>' does. + + Note that digit grouping specified by the 'istream' locale is +currently not accepted. Perhaps this will change in the future. + + + These operators mean that GMP types can be read in the usual C++ way, +for example, + + mpz_t z; + ... + cin >> z; + + But note that 'istream' input (and 'ostream' output, *note C++ +Formatted Output::) is the only overloading available for the GMP types +and that for instance using '+' with an 'mpz_t' will have unpredictable +results. For classes with overloading, see *note C++ Class Interface::. + + +File: gmp.info, Node: C++ Class Interface, Next: Custom Allocation, Prev: Formatted Input, Up: Top + +12 C++ Class Interface +********************** + +This chapter describes the C++ class based interface to GMP. + + All GMP C language types and functions can be used in C++ programs, +since 'gmp.h' has 'extern "C"' qualifiers, but the class interface +offers overloaded functions and operators which may be more convenient. + + Due to the implementation of this interface, a reasonably recent C++ +compiler is required, one supporting namespaces, partial specialization +of templates and member templates. + + *Everything described in this chapter is to be considered preliminary +and might be subject to incompatible changes if some unforeseen +difficulty reveals itself.* + +* Menu: + +* C++ Interface General:: +* C++ Interface Integers:: +* C++ Interface Rationals:: +* C++ Interface Floats:: +* C++ Interface Random Numbers:: +* C++ Interface Limitations:: + + +File: gmp.info, Node: C++ Interface General, Next: C++ Interface Integers, Prev: C++ Class Interface, Up: C++ Class Interface + +12.1 C++ Interface General +========================== + +All the C++ classes and functions are available with + + #include + + Programs should be linked with the 'libgmpxx' and 'libgmp' libraries. +For example, + + g++ mycxxprog.cc -lgmpxx -lgmp + +The classes defined are + + -- Class: mpz_class + -- Class: mpq_class + -- Class: mpf_class + + The standard operators and various standard functions are overloaded +to allow arithmetic with these classes. For example, + + int + main (void) + { + mpz_class a, b, c; + + a = 1234; + b = "-5678"; + c = a+b; + cout << "sum is " << c << "\n"; + cout << "absolute value is " << abs(c) << "\n"; + + return 0; + } + + An important feature of the implementation is that an expression like +'a=b+c' results in a single call to the corresponding 'mpz_add', without +using a temporary for the 'b+c' part. Expressions which by their nature +imply intermediate values, like 'a=b*c+d*e', still use temporaries +though. + + The classes can be freely intermixed in expressions, as can the +classes and the standard types 'long', 'unsigned long' and 'double'. +Smaller types like 'int' or 'float' can also be intermixed, since C++ +will promote them. + + Note that 'bool' is not accepted directly, but must be explicitly +cast to an 'int' first. This is because C++ will automatically convert +any pointer to a 'bool', so if GMP accepted 'bool' it would make all +sorts of invalid class and pointer combinations compile but almost +certainly not do anything sensible. + + Conversions back from the classes to standard C++ types aren't done +automatically, instead member functions like 'get_si' are provided (see +the following sections for details). + + Also there are no automatic conversions from the classes to the +corresponding GMP C types, instead a reference to the underlying C +object can be obtained with the following functions, + + -- Function: mpz_t mpz_class::get_mpz_t () + -- Function: mpq_t mpq_class::get_mpq_t () + -- Function: mpf_t mpf_class::get_mpf_t () + + These can be used to call a C function which doesn't have a C++ class +interface. For example to set 'a' to the GCD of 'b' and 'c', + + mpz_class a, b, c; + ... + mpz_gcd (a.get_mpz_t(), b.get_mpz_t(), c.get_mpz_t()); + + In the other direction, a class can be initialized from the +corresponding GMP C type, or assigned to if an explicit constructor is +used. In both cases this makes a copy of the value, it doesn't create +any sort of association. For example, + + mpz_t z; + // ... init and calculate z ... + mpz_class x(z); + mpz_class y; + y = mpz_class (z); + + There are no namespace setups in 'gmpxx.h', all types and functions +are simply put into the global namespace. This is what 'gmp.h' has done +in the past, and continues to do for compatibility. The extras provided +by 'gmpxx.h' follow GMP naming conventions and are unlikely to clash +with anything. + + +File: gmp.info, Node: C++ Interface Integers, Next: C++ Interface Rationals, Prev: C++ Interface General, Up: C++ Class Interface + +12.2 C++ Interface Integers +=========================== + + -- Function: mpz_class::mpz_class (type N) + Construct an 'mpz_class'. All the standard C++ types may be used, + except 'long long' and 'long double', and all the GMP C++ classes + can be used, although conversions from 'mpq_class' and 'mpf_class' + are 'explicit'. Any necessary conversion follows the corresponding + C function, for example 'double' follows 'mpz_set_d' (*note + Assigning Integers::). + + -- Function: explicit mpz_class::mpz_class (const mpz_t Z) + Construct an 'mpz_class' from an 'mpz_t'. The value in Z is copied + into the new 'mpz_class', there won't be any permanent association + between it and Z. + + -- Function: explicit mpz_class::mpz_class (const char *S, int BASE = + 0) + -- Function: explicit mpz_class::mpz_class (const string& S, int BASE = + 0) + Construct an 'mpz_class' converted from a string using + 'mpz_set_str' (*note Assigning Integers::). + + If the string is not a valid integer, an 'std::invalid_argument' + exception is thrown. The same applies to 'operator='. + + -- Function: mpz_class operator"" _mpz (const char *STR) + With C++11 compilers, integers can be constructed with the syntax + '123_mpz' which is equivalent to 'mpz_class("123")'. + + -- Function: mpz_class operator/ (mpz_class A, mpz_class D) + -- Function: mpz_class operator% (mpz_class A, mpz_class D) + Divisions involving 'mpz_class' round towards zero, as per the + 'mpz_tdiv_q' and 'mpz_tdiv_r' functions (*note Integer Division::). + This is the same as the C99 '/' and '%' operators. + + The 'mpz_fdiv...' or 'mpz_cdiv...' functions can always be called + directly if desired. For example, + + mpz_class q, a, d; + ... + mpz_fdiv_q (q.get_mpz_t(), a.get_mpz_t(), d.get_mpz_t()); + + -- Function: mpz_class abs (mpz_class OP) + -- Function: int cmp (mpz_class OP1, type OP2) + -- Function: int cmp (type OP1, mpz_class OP2) + + -- Function: bool mpz_class::fits_sint_p (void) + -- Function: bool mpz_class::fits_slong_p (void) + -- Function: bool mpz_class::fits_sshort_p (void) + + -- Function: bool mpz_class::fits_uint_p (void) + -- Function: bool mpz_class::fits_ulong_p (void) + -- Function: bool mpz_class::fits_ushort_p (void) + + -- Function: double mpz_class::get_d (void) + -- Function: long mpz_class::get_si (void) + -- Function: string mpz_class::get_str (int BASE = 10) + -- Function: unsigned long mpz_class::get_ui (void) + + -- Function: int mpz_class::set_str (const char *STR, int BASE) + -- Function: int mpz_class::set_str (const string& STR, int BASE) + -- Function: int sgn (mpz_class OP) + -- Function: mpz_class sqrt (mpz_class OP) + + -- Function: mpz_class gcd (mpz_class OP1, mpz_class OP2) + -- Function: mpz_class lcm (mpz_class OP1, mpz_class OP2) + -- Function: mpz_class mpz_class::factorial (type OP) + -- Function: mpz_class factorial (mpz_class OP) + -- Function: mpz_class mpz_class::primorial (type OP) + -- Function: mpz_class primorial (mpz_class OP) + -- Function: mpz_class mpz_class::fibonacci (type OP) + -- Function: mpz_class fibonacci (mpz_class OP) + + -- Function: void mpz_class::swap (mpz_class& OP) + -- Function: void swap (mpz_class& OP1, mpz_class& OP2) + These functions provide a C++ class interface to the corresponding + GMP C routines. Calling 'factorial' or 'primorial' on a negative + number is undefined. + + 'cmp' can be used with any of the classes or the standard C++ + types, except 'long long' and 'long double'. + + + Overloaded operators for combinations of 'mpz_class' and 'double' are +provided for completeness, but it should be noted that if the given +'double' is not an integer then the way any rounding is done is +currently unspecified. The rounding might take place at the start, in +the middle, or at the end of the operation, and it might change in the +future. + + Conversions between 'mpz_class' and 'double', however, are defined to +follow the corresponding C functions 'mpz_get_d' and 'mpz_set_d'. And +comparisons are always made exactly, as per 'mpz_cmp_d'. + + +File: gmp.info, Node: C++ Interface Rationals, Next: C++ Interface Floats, Prev: C++ Interface Integers, Up: C++ Class Interface + +12.3 C++ Interface Rationals +============================ + +In all the following constructors, if a fraction is given then it should +be in canonical form, or if not then 'mpq_class::canonicalize' called. + + -- Function: mpq_class::mpq_class (type OP) + -- Function: mpq_class::mpq_class (integer NUM, integer DEN) + Construct an 'mpq_class'. The initial value can be a single value + of any type (conversion from 'mpf_class' is 'explicit'), or a pair + of integers ('mpz_class' or standard C++ integer types) + representing a fraction, except that 'long long' and 'long double' + are not supported. For example, + + mpq_class q (99); + mpq_class q (1.75); + mpq_class q (1, 3); + + -- Function: explicit mpq_class::mpq_class (const mpq_t Q) + Construct an 'mpq_class' from an 'mpq_t'. The value in Q is copied + into the new 'mpq_class', there won't be any permanent association + between it and Q. + + -- Function: explicit mpq_class::mpq_class (const char *S, int BASE = + 0) + -- Function: explicit mpq_class::mpq_class (const string& S, int BASE = + 0) + Construct an 'mpq_class' converted from a string using + 'mpq_set_str' (*note Initializing Rationals::). + + If the string is not a valid rational, an 'std::invalid_argument' + exception is thrown. The same applies to 'operator='. + + -- Function: mpq_class operator"" _mpq (const char *STR) + With C++11 compilers, integral rationals can be constructed with + the syntax '123_mpq' which is equivalent to 'mpq_class(123_mpz)'. + Other rationals can be built as '-1_mpq/2' or '0xb_mpq/123456_mpz'. + + -- Function: void mpq_class::canonicalize () + Put an 'mpq_class' into canonical form, as per *note Rational + Number Functions::. All arithmetic operators require their + operands in canonical form, and will return results in canonical + form. + + -- Function: mpq_class abs (mpq_class OP) + -- Function: int cmp (mpq_class OP1, type OP2) + -- Function: int cmp (type OP1, mpq_class OP2) + + -- Function: double mpq_class::get_d (void) + -- Function: string mpq_class::get_str (int BASE = 10) + + -- Function: int mpq_class::set_str (const char *STR, int BASE) + -- Function: int mpq_class::set_str (const string& STR, int BASE) + -- Function: int sgn (mpq_class OP) + + -- Function: void mpq_class::swap (mpq_class& OP) + -- Function: void swap (mpq_class& OP1, mpq_class& OP2) + These functions provide a C++ class interface to the corresponding + GMP C routines. + + 'cmp' can be used with any of the classes or the standard C++ + types, except 'long long' and 'long double'. + + -- Function: mpz_class& mpq_class::get_num () + -- Function: mpz_class& mpq_class::get_den () + Get a reference to an 'mpz_class' which is the numerator or + denominator of an 'mpq_class'. This can be used both for read and + write access. If the object returned is modified, it modifies the + original 'mpq_class'. + + If direct manipulation might produce a non-canonical value, then + 'mpq_class::canonicalize' must be called before further operations. + + -- Function: mpz_t mpq_class::get_num_mpz_t () + -- Function: mpz_t mpq_class::get_den_mpz_t () + Get a reference to the underlying 'mpz_t' numerator or denominator + of an 'mpq_class'. This can be passed to C functions expecting an + 'mpz_t'. Any modifications made to the 'mpz_t' will modify the + original 'mpq_class'. + + If direct manipulation might produce a non-canonical value, then + 'mpq_class::canonicalize' must be called before further operations. + + -- Function: istream& operator>> (istream& STREAM, mpq_class& ROP); + Read ROP from STREAM, using its 'ios' formatting settings, the same + as 'mpq_t operator>>' (*note C++ Formatted Input::). + + If the ROP read might not be in canonical form then + 'mpq_class::canonicalize' must be called. + + +File: gmp.info, Node: C++ Interface Floats, Next: C++ Interface Random Numbers, Prev: C++ Interface Rationals, Up: C++ Class Interface + +12.4 C++ Interface Floats +========================= + +When an expression requires the use of temporary intermediate +'mpf_class' values, like 'f=g*h+x*y', those temporaries will have the +same precision as the destination 'f'. Explicit constructors can be +used if this doesn't suit. + + -- Function: mpf_class::mpf_class (type OP) + -- Function: mpf_class::mpf_class (type OP, mp_bitcnt_t PREC) + Construct an 'mpf_class'. Any standard C++ type can be used, + except 'long long' and 'long double', and any of the GMP C++ + classes can be used. + + If PREC is given, the initial precision is that value, in bits. If + PREC is not given, then the initial precision is determined by the + type of OP given. An 'mpz_class', 'mpq_class', or C++ builtin type + will give the default 'mpf' precision (*note Initializing + Floats::). An 'mpf_class' or expression will give the precision of + that value. The precision of a binary expression is the higher of + the two operands. + + mpf_class f(1.5); // default precision + mpf_class f(1.5, 500); // 500 bits (at least) + mpf_class f(x); // precision of x + mpf_class f(abs(x)); // precision of x + mpf_class f(-g, 1000); // 1000 bits (at least) + mpf_class f(x+y); // greater of precisions of x and y + + -- Function: explicit mpf_class::mpf_class (const mpf_t F) + -- Function: mpf_class::mpf_class (const mpf_t F, mp_bitcnt_t PREC) + Construct an 'mpf_class' from an 'mpf_t'. The value in F is copied + into the new 'mpf_class', there won't be any permanent association + between it and F. + + If PREC is given, the initial precision is that value, in bits. If + PREC is not given, then the initial precision is that of F. + + -- Function: explicit mpf_class::mpf_class (const char *S) + -- Function: mpf_class::mpf_class (const char *S, mp_bitcnt_t PREC, int + BASE = 0) + -- Function: explicit mpf_class::mpf_class (const string& S) + -- Function: mpf_class::mpf_class (const string& S, mp_bitcnt_t PREC, + int BASE = 0) + Construct an 'mpf_class' converted from a string using + 'mpf_set_str' (*note Assigning Floats::). If PREC is given, the + initial precision is that value, in bits. If not, the default + 'mpf' precision (*note Initializing Floats::) is used. + + If the string is not a valid float, an 'std::invalid_argument' + exception is thrown. The same applies to 'operator='. + + -- Function: mpf_class operator"" _mpf (const char *STR) + With C++11 compilers, floats can be constructed with the syntax + '1.23e-1_mpf' which is equivalent to 'mpf_class("1.23e-1")'. + + -- Function: mpf_class& mpf_class::operator= (type OP) + Convert and store the given OP value to an 'mpf_class' object. The + same types are accepted as for the constructors above. + + Note that 'operator=' only stores a new value, it doesn't copy or + change the precision of the destination, instead the value is + truncated if necessary. This is the same as 'mpf_set' etc. Note + in particular this means for 'mpf_class' a copy constructor is not + the same as a default constructor plus assignment. + + mpf_class x (y); // x created with precision of y + + mpf_class x; // x created with default precision + x = y; // value truncated to that precision + + Applications using templated code may need to be careful about the + assumptions the code makes in this area, when working with + 'mpf_class' values of various different or non-default precisions. + For instance implementations of the standard 'complex' template + have been seen in both styles above, though of course 'complex' is + normally only actually specified for use with the builtin float + types. + + -- Function: mpf_class abs (mpf_class OP) + -- Function: mpf_class ceil (mpf_class OP) + -- Function: int cmp (mpf_class OP1, type OP2) + -- Function: int cmp (type OP1, mpf_class OP2) + + -- Function: bool mpf_class::fits_sint_p (void) + -- Function: bool mpf_class::fits_slong_p (void) + -- Function: bool mpf_class::fits_sshort_p (void) + + -- Function: bool mpf_class::fits_uint_p (void) + -- Function: bool mpf_class::fits_ulong_p (void) + -- Function: bool mpf_class::fits_ushort_p (void) + + -- Function: mpf_class floor (mpf_class OP) + -- Function: mpf_class hypot (mpf_class OP1, mpf_class OP2) + + -- Function: double mpf_class::get_d (void) + -- Function: long mpf_class::get_si (void) + -- Function: string mpf_class::get_str (mp_exp_t& EXP, int BASE = 10, + size_t DIGITS = 0) + -- Function: unsigned long mpf_class::get_ui (void) + + -- Function: int mpf_class::set_str (const char *STR, int BASE) + -- Function: int mpf_class::set_str (const string& STR, int BASE) + -- Function: int sgn (mpf_class OP) + -- Function: mpf_class sqrt (mpf_class OP) + + -- Function: void mpf_class::swap (mpf_class& OP) + -- Function: void swap (mpf_class& OP1, mpf_class& OP2) + -- Function: mpf_class trunc (mpf_class OP) + These functions provide a C++ class interface to the corresponding + GMP C routines. + + 'cmp' can be used with any of the classes or the standard C++ + types, except 'long long' and 'long double'. + + The accuracy provided by 'hypot' is not currently guaranteed. + + -- Function: mp_bitcnt_t mpf_class::get_prec () + -- Function: void mpf_class::set_prec (mp_bitcnt_t PREC) + -- Function: void mpf_class::set_prec_raw (mp_bitcnt_t PREC) + Get or set the current precision of an 'mpf_class'. + + The restrictions described for 'mpf_set_prec_raw' (*note + Initializing Floats::) apply to 'mpf_class::set_prec_raw'. Note in + particular that the 'mpf_class' must be restored to its allocated + precision before being destroyed. This must be done by application + code, there's no automatic mechanism for it. + + +File: gmp.info, Node: C++ Interface Random Numbers, Next: C++ Interface Limitations, Prev: C++ Interface Floats, Up: C++ Class Interface + +12.5 C++ Interface Random Numbers +================================= + + -- Class: gmp_randclass + The C++ class interface to the GMP random number functions uses + 'gmp_randclass' to hold an algorithm selection and current state, + as per 'gmp_randstate_t'. + + -- Function: gmp_randclass::gmp_randclass (void (*RANDINIT) + (gmp_randstate_t, ...), ...) + Construct a 'gmp_randclass', using a call to the given RANDINIT + function (*note Random State Initialization::). The arguments + expected are the same as RANDINIT, but with 'mpz_class' instead of + 'mpz_t'. For example, + + gmp_randclass r1 (gmp_randinit_default); + gmp_randclass r2 (gmp_randinit_lc_2exp_size, 32); + gmp_randclass r3 (gmp_randinit_lc_2exp, a, c, m2exp); + gmp_randclass r4 (gmp_randinit_mt); + + 'gmp_randinit_lc_2exp_size' will fail if the size requested is too + big, an 'std::length_error' exception is thrown in that case. + + -- Function: gmp_randclass::gmp_randclass (gmp_randalg_t ALG, ...) + Construct a 'gmp_randclass' using the same parameters as + 'gmp_randinit' (*note Random State Initialization::). This + function is obsolete and the above RANDINIT style should be + preferred. + + -- Function: void gmp_randclass::seed (unsigned long int S) + -- Function: void gmp_randclass::seed (mpz_class S) + Seed a random number generator. See *note Random Number + Functions::, for how to choose a good seed. + + -- Function: mpz_class gmp_randclass::get_z_bits (mp_bitcnt_t BITS) + -- Function: mpz_class gmp_randclass::get_z_bits (mpz_class BITS) + Generate a random integer with a specified number of bits. + + -- Function: mpz_class gmp_randclass::get_z_range (mpz_class N) + Generate a random integer in the range 0 to N-1 inclusive. + + -- Function: mpf_class gmp_randclass::get_f () + -- Function: mpf_class gmp_randclass::get_f (mp_bitcnt_t PREC) + Generate a random float F in the range 0 <= F < 1. F will be to + PREC bits precision, or if PREC is not given then to the precision + of the destination. For example, + + gmp_randclass r; + ... + mpf_class f (0, 512); // 512 bits precision + f = r.get_f(); // random number, 512 bits + + +File: gmp.info, Node: C++ Interface Limitations, Prev: C++ Interface Random Numbers, Up: C++ Class Interface + +12.6 C++ Interface Limitations +============================== + +'mpq_class' and Templated Reading + A generic piece of template code probably won't know that + 'mpq_class' requires a 'canonicalize' call if inputs read with + 'operator>>' might be non-canonical. This can lead to incorrect + results. + + 'operator>>' behaves as it does for reasons of efficiency. A + canonicalize can be quite time consuming on large operands, and is + best avoided if it's not necessary. + + But this potential difficulty reduces the usefulness of + 'mpq_class'. Perhaps a mechanism to tell 'operator>>' what to do + will be adopted in the future, maybe a preprocessor define, a + global flag, or an 'ios' flag pressed into service. Or maybe, at + the risk of inconsistency, the 'mpq_class' 'operator>>' could + canonicalize and leave 'mpq_t' 'operator>>' not doing so, for use + on those occasions when that's acceptable. Send feedback or + alternate ideas to . + +Subclassing + Subclassing the GMP C++ classes works, but is not currently + recommended. + + Expressions involving subclasses resolve correctly (or seem to), + but in normal C++ fashion the subclass doesn't inherit constructors + and assignments. There's many of those in the GMP classes, and a + good way to reestablish them in a subclass is not yet provided. + +Templated Expressions + A subtle difficulty exists when using expressions together with + application-defined template functions. Consider the following, + with 'T' intended to be some numeric type, + + template + T fun (const T &, const T &); + + When used with, say, plain 'mpz_class' variables, it works fine: + 'T' is resolved as 'mpz_class'. + + mpz_class f(1), g(2); + fun (f, g); // Good + + But when one of the arguments is an expression, it doesn't work. + + mpz_class f(1), g(2), h(3); + fun (f, g+h); // Bad + + This is because 'g+h' ends up being a certain expression template + type internal to 'gmpxx.h', which the C++ template resolution rules + are unable to automatically convert to 'mpz_class'. The workaround + is simply to add an explicit cast. + + mpz_class f(1), g(2), h(3); + fun (f, mpz_class(g+h)); // Good + + Similarly, within 'fun' it may be necessary to cast an expression + to type 'T' when calling a templated 'fun2'. + + template + void fun (T f, T g) + { + fun2 (f, f+g); // Bad + } + + template + void fun (T f, T g) + { + fun2 (f, T(f+g)); // Good + } + +C++11 + C++11 provides several new ways in which types can be inferred: + 'auto', 'decltype', etc. While they can be very convenient, they + don't mix well with expression templates. In this example, the + addition is performed twice, as if we had defined 'sum' as a macro. + + mpz_class z = 33; + auto sum = z + z; + mpz_class prod = sum * sum; + + This other example may crash, though some compilers might make it + look like it is working, because the expression 'z+z' goes out of + scope before it is evaluated. + + mpz_class z = 33; + auto sum = z + z + z; + mpz_class prod = sum * 2; + + It is thus strongly recommended to avoid 'auto' anywhere a GMP C++ + expression may appear. + + +File: gmp.info, Node: Custom Allocation, Next: Language Bindings, Prev: C++ Class Interface, Up: Top + +13 Custom Allocation +******************** + +By default GMP uses 'malloc', 'realloc' and 'free' for memory +allocation, and if they fail GMP prints a message to the standard error +output and terminates the program. + + Alternate functions can be specified, to allocate memory in a +different way or to have a different error action on running out of +memory. + + -- Function: void mp_set_memory_functions ( + void *(*ALLOC_FUNC_PTR) (size_t), + void *(*REALLOC_FUNC_PTR) (void *, size_t, size_t), + void (*FREE_FUNC_PTR) (void *, size_t)) + Replace the current allocation functions from the arguments. If an + argument is 'NULL', the corresponding default function is used. + + These functions will be used for all memory allocation done by GMP, + apart from temporary space from 'alloca' if that function is + available and GMP is configured to use it (*note Build Options::). + + *Be sure to call 'mp_set_memory_functions' only when there are no + active GMP objects allocated using the previous memory functions! + Usually that means calling it before any other GMP function.* + + The functions supplied should fit the following declarations: + + -- Function: void * allocate_function (size_t ALLOC_SIZE) + Return a pointer to newly allocated space with at least ALLOC_SIZE + bytes. + + -- Function: void * reallocate_function (void *PTR, size_t OLD_SIZE, + size_t NEW_SIZE) + Resize a previously allocated block PTR of OLD_SIZE bytes to be + NEW_SIZE bytes. + + The block may be moved if necessary or if desired, and in that case + the smaller of OLD_SIZE and NEW_SIZE bytes must be copied to the + new location. The return value is a pointer to the resized block, + that being the new location if moved or just PTR if not. + + PTR is never 'NULL', it's always a previously allocated block. + NEW_SIZE may be bigger or smaller than OLD_SIZE. + + -- Function: void free_function (void *PTR, size_t SIZE) + De-allocate the space pointed to by PTR. + + PTR is never 'NULL', it's always a previously allocated block of + SIZE bytes. + + A "byte" here means the unit used by the 'sizeof' operator. + + The REALLOCATE_FUNCTION parameter OLD_SIZE and the FREE_FUNCTION +parameter SIZE are passed for convenience, but of course they can be +ignored if not needed by an implementation. The default functions using +'malloc' and friends for instance don't use them. + + No error return is allowed from any of these functions, if they +return then they must have performed the specified operation. In +particular note that ALLOCATE_FUNCTION or REALLOCATE_FUNCTION mustn't +return 'NULL'. + + Getting a different fatal error action is a good use for custom +allocation functions, for example giving a graphical dialog rather than +the default print to 'stderr'. How much is possible when genuinely out +of memory is another question though. + + There's currently no defined way for the allocation functions to +recover from an error such as out of memory, they must terminate program +execution. A 'longjmp' or throwing a C++ exception will have undefined +results. This may change in the future. + + GMP may use allocated blocks to hold pointers to other allocated +blocks. This will limit the assumptions a conservative garbage +collection scheme can make. + + Since the default GMP allocation uses 'malloc' and friends, those +functions will be linked in even if the first thing a program does is an +'mp_set_memory_functions'. It's necessary to change the GMP sources if +this is a problem. + + + -- Function: void mp_get_memory_functions ( + void *(**ALLOC_FUNC_PTR) (size_t), + void *(**REALLOC_FUNC_PTR) (void *, size_t, size_t), + void (**FREE_FUNC_PTR) (void *, size_t)) + Get the current allocation functions, storing function pointers to + the locations given by the arguments. If an argument is 'NULL', + that function pointer is not stored. + + For example, to get just the current free function, + + void (*freefunc) (void *, size_t); + + mp_get_memory_functions (NULL, NULL, &freefunc); + + +File: gmp.info, Node: Language Bindings, Next: Algorithms, Prev: Custom Allocation, Up: Top + +14 Language Bindings +******************** + +The following packages and projects offer access to GMP from languages +other than C, though perhaps with varying levels of functionality and +efficiency. + + +C++ + * GMP C++ class interface, *note C++ Class Interface:: + Straightforward interface, expression templates to eliminate + temporaries. + * ALP + Linear algebra and polynomials using templates. + * CLN + High level classes for arithmetic. + * Linbox + Sparse vectors and matrices. + * NTL + A C++ number theory library. + +Eiffel + * Eiffelroom + +Haskell + * Glasgow Haskell Compiler + +Java + * Kaffe + +Lisp + * GNU Common Lisp + * Librep + * XEmacs (21.5.18 beta and up) + Optional big integers, rationals and floats using GMP. + +ML + * MLton compiler + +Objective Caml + * MLGMP + * Numerix + Optionally using GMP. + +Oz + * Mozart + +Pascal + * GNU Pascal Compiler + GMP unit. + * Numerix + For Free Pascal, optionally using GMP. + +Perl + * GMP module, see 'demos/perl' in the GMP sources (*note + Demonstration Programs::). + * Math::GMP + Compatible with Math::BigInt, but not as many functions as the + GMP module above. + * Math::BigInt::GMP + Plug Math::GMP into normal Math::BigInt operations. + +Pike + * pikempz module in the standard distribution, + + +Prolog + * SWI Prolog + Arbitrary precision floats. + +Python + * GMPY + +Ruby + * + +Scheme + * GNU Guile + * RScheme + * STklos + +Smalltalk + * GNU Smalltalk + +Other + * Axiom + Computer algebra using GCL. + * DrGenius + Geometry system and mathematical programming language. + * GiNaC + C++ computer algebra using CLN. + * GOO + Dynamic object oriented language. + * Maxima + Macsyma computer algebra using GCL. + * Regina + Topological calculator. + * Yacas + Yet another computer algebra system. + + +File: gmp.info, Node: Algorithms, Next: Internals, Prev: Language Bindings, Up: Top + +15 Algorithms +************* + +This chapter is an introduction to some of the algorithms used for +various GMP operations. The code is likely to be hard to understand +without knowing something about the algorithms. + + Some GMP internals are mentioned, but applications that expect to be +compatible with future GMP releases should take care to use only the +documented functions. + +* Menu: + +* Multiplication Algorithms:: +* Division Algorithms:: +* Greatest Common Divisor Algorithms:: +* Powering Algorithms:: +* Root Extraction Algorithms:: +* Radix Conversion Algorithms:: +* Other Algorithms:: +* Assembly Coding:: + + +File: gmp.info, Node: Multiplication Algorithms, Next: Division Algorithms, Prev: Algorithms, Up: Algorithms + +15.1 Multiplication +=================== + +NxN limb multiplications and squares are done using one of seven +algorithms, as the size N increases. + + Algorithm Threshold + Basecase (none) + Karatsuba 'MUL_TOOM22_THRESHOLD' + Toom-3 'MUL_TOOM33_THRESHOLD' + Toom-4 'MUL_TOOM44_THRESHOLD' + Toom-6.5 'MUL_TOOM6H_THRESHOLD' + Toom-8.5 'MUL_TOOM8H_THRESHOLD' + FFT 'MUL_FFT_THRESHOLD' + + Similarly for squaring, with the 'SQR' thresholds. + + NxM multiplications of operands with different sizes above +'MUL_TOOM22_THRESHOLD' are currently done by special Toom-inspired +algorithms or directly with FFT, depending on operand size (*note +Unbalanced Multiplication::). + +* Menu: + +* Basecase Multiplication:: +* Karatsuba Multiplication:: +* Toom 3-Way Multiplication:: +* Toom 4-Way Multiplication:: +* Higher degree Toom'n'half:: +* FFT Multiplication:: +* Other Multiplication:: +* Unbalanced Multiplication:: + + +File: gmp.info, Node: Basecase Multiplication, Next: Karatsuba Multiplication, Prev: Multiplication Algorithms, Up: Multiplication Algorithms + +15.1.1 Basecase Multiplication +------------------------------ + +Basecase NxM multiplication is a straightforward rectangular set of +cross-products, the same as long multiplication done by hand and for +that reason sometimes known as the schoolbook or grammar school method. +This is an O(N*M) algorithm. See Knuth section 4.3.1 algorithm M (*note +References::), and the 'mpn/generic/mul_basecase.c' code. + + Assembly implementations of 'mpn_mul_basecase' are essentially the +same as the generic C code, but have all the usual assembly tricks and +obscurities introduced for speed. + + A square can be done in roughly half the time of a multiply, by using +the fact that the cross products above and below the diagonal are the +same. A triangle of products below the diagonal is formed, doubled +(left shift by one bit), and then the products on the diagonal added. +This can be seen in 'mpn/generic/sqr_basecase.c'. Again the assembly +implementations take essentially the same approach. + + u0 u1 u2 u3 u4 + +---+---+---+---+---+ + u0 | d | | | | | + +---+---+---+---+---+ + u1 | | d | | | | + +---+---+---+---+---+ + u2 | | | d | | | + +---+---+---+---+---+ + u3 | | | | d | | + +---+---+---+---+---+ + u4 | | | | | d | + +---+---+---+---+---+ + + In practice squaring isn't a full 2x faster than multiplying, it's +usually around 1.5x. Less than 1.5x probably indicates +'mpn_sqr_basecase' wants improving on that CPU. + + On some CPUs 'mpn_mul_basecase' can be faster than the generic C +'mpn_sqr_basecase' on some small sizes. 'SQR_BASECASE_THRESHOLD' is the +size at which to use 'mpn_sqr_basecase', this will be zero if that +routine should be used always. + + +File: gmp.info, Node: Karatsuba Multiplication, Next: Toom 3-Way Multiplication, Prev: Basecase Multiplication, Up: Multiplication Algorithms + +15.1.2 Karatsuba Multiplication +------------------------------- + +The Karatsuba multiplication algorithm is described in Knuth section +4.3.3 part A, and various other textbooks. A brief description is given +here. + + The inputs x and y are treated as each split into two parts of equal +length (or the most significant part one limb shorter if N is odd). + + high low + +----------+----------+ + | x1 | x0 | + +----------+----------+ + + +----------+----------+ + | y1 | y0 | + +----------+----------+ + + Let b be the power of 2 where the split occurs, i.e. if x0 is k limbs +(y0 the same) then b=2^(k*mp_bits_per_limb). With that x=x1*b+x0 and +y=y1*b+y0, and the following holds, + + x*y = (b^2+b)*x1*y1 - b*(x1-x0)*(y1-y0) + (b+1)*x0*y0 + + This formula means doing only three multiplies of (N/2)x(N/2) limbs, +whereas a basecase multiply of NxN limbs is equivalent to four +multiplies of (N/2)x(N/2). The factors (b^2+b) etc represent the +positions where the three products must be added. + + high low + +--------+--------+ +--------+--------+ + | x1*y1 | | x0*y0 | + +--------+--------+ +--------+--------+ + +--------+--------+ + add | x1*y1 | + +--------+--------+ + +--------+--------+ + add | x0*y0 | + +--------+--------+ + +--------+--------+ + sub | (x1-x0)*(y1-y0) | + +--------+--------+ + + The term (x1-x0)*(y1-y0) is best calculated as an absolute value, and +the sign used to choose to add or subtract. Notice the sum +high(x0*y0)+low(x1*y1) occurs twice, so it's possible to do 5*k limb +additions, rather than 6*k, but in GMP extra function call overheads +outweigh the saving. + + Squaring is similar to multiplying, but with x=y the formula reduces +to an equivalent with three squares, + + x^2 = (b^2+b)*x1^2 - b*(x1-x0)^2 + (b+1)*x0^2 + + The final result is accumulated from those three squares the same way +as for the three multiplies above. The middle term (x1-x0)^2 is now +always positive. + + A similar formula for both multiplying and squaring can be +constructed with a middle term (x1+x0)*(y1+y0). But those sums can +exceed k limbs, leading to more carry handling and additions than the +form above. + + Karatsuba multiplication is asymptotically an O(N^1.585) algorithm, +the exponent being log(3)/log(2), representing 3 multiplies each 1/2 the +size of the inputs. This is a big improvement over the basecase +multiply at O(N^2) and the advantage soon overcomes the extra additions +Karatsuba performs. 'MUL_TOOM22_THRESHOLD' can be as little as 10 +limbs. The 'SQR' threshold is usually about twice the 'MUL'. + + The basecase algorithm will take a time of the form M(N) = a*N^2 + +b*N + c and the Karatsuba algorithm K(N) = 3*M(N/2) + d*N + e, which +expands to K(N) = 3/4*a*N^2 + 3/2*b*N + 3*c + d*N + e. The factor 3/4 +for a means per-crossproduct speedups in the basecase code will increase +the threshold since they benefit M(N) more than K(N). And conversely the +3/2 for b means linear style speedups of b will increase the threshold +since they benefit K(N) more than M(N). The latter can be seen for +instance when adding an optimized 'mpn_sqr_diagonal' to +'mpn_sqr_basecase'. Of course all speedups reduce total time, and in +that sense the algorithm thresholds are merely of academic interest. + + +File: gmp.info, Node: Toom 3-Way Multiplication, Next: Toom 4-Way Multiplication, Prev: Karatsuba Multiplication, Up: Multiplication Algorithms + +15.1.3 Toom 3-Way Multiplication +-------------------------------- + +The Karatsuba formula is the simplest case of a general approach to +splitting inputs that leads to both Toom and FFT algorithms. A +description of Toom can be found in Knuth section 4.3.3, with an example +3-way calculation after Theorem A. The 3-way form used in GMP is +described here. + + The operands are each considered split into 3 pieces of equal length +(or the most significant part 1 or 2 limbs shorter than the other two). + + high low + +----------+----------+----------+ + | x2 | x1 | x0 | + +----------+----------+----------+ + + +----------+----------+----------+ + | y2 | y1 | y0 | + +----------+----------+----------+ + +These parts are treated as the coefficients of two polynomials + + X(t) = x2*t^2 + x1*t + x0 + Y(t) = y2*t^2 + y1*t + y0 + + Let b equal the power of 2 which is the size of the x0, x1, y0 and y1 +pieces, i.e. if they're k limbs each then b=2^(k*mp_bits_per_limb). +With this x=X(b) and y=Y(b). + + Let a polynomial W(t)=X(t)*Y(t) and suppose its coefficients are + + W(t) = w4*t^4 + w3*t^3 + w2*t^2 + w1*t + w0 + + The w[i] are going to be determined, and when they are they'll give +the final result using w=W(b), since x*y=X(b)*Y(b)=W(b). The +coefficients will be roughly b^2 each, and the final W(b) will be an +addition like this: + + high low + +-------+-------+ + | w4 | + +-------+-------+ + +--------+-------+ + | w3 | + +--------+-------+ + +--------+-------+ + | w2 | + +--------+-------+ + +--------+-------+ + | w1 | + +--------+-------+ + +-------+-------+ + | w0 | + +-------+-------+ + + The w[i] coefficients could be formed by a simple set of cross +products, like w4=x2*y2, w3=x2*y1+x1*y2, w2=x2*y0+x1*y1+x0*y2 etc, but +this would need all nine x[i]*y[j] for i,j=0,1,2, and would be +equivalent merely to a basecase multiply. Instead the following +approach is used. + + X(t) and Y(t) are evaluated and multiplied at 5 points, giving values +of W(t) at those points. In GMP the following points are used: + + Point Value + t=0 x0 * y0, which gives w0 immediately + t=1 (x2+x1+x0) * (y2+y1+y0) + t=-1 (x2-x1+x0) * (y2-y1+y0) + t=2 (4*x2+2*x1+x0) * (4*y2+2*y1+y0) + t=inf x2 * y2, which gives w4 immediately + + At t=-1 the values can be negative and that's handled using the +absolute values and tracking the sign separately. At t=inf the value is +actually X(t)*Y(t)/t^4 in the limit as t approaches infinity, but it's +much easier to think of as simply x2*y2 giving w4 immediately (much like +x0*y0 at t=0 gives w0 immediately). + + Each of the points substituted into W(t)=w4*t^4+...+w0 gives a linear +combination of the w[i] coefficients, and the value of those +combinations has just been calculated. + + W(0) = w0 + W(1) = w4 + w3 + w2 + w1 + w0 + W(-1) = w4 - w3 + w2 - w1 + w0 + W(2) = 16*w4 + 8*w3 + 4*w2 + 2*w1 + w0 + W(inf) = w4 + + This is a set of five equations in five unknowns, and some elementary +linear algebra quickly isolates each w[i]. This involves adding or +subtracting one W(t) value from another, and a couple of divisions by +powers of 2 and one division by 3, the latter using the special +'mpn_divexact_by3' (*note Exact Division::). + + The conversion of W(t) values to the coefficients is interpolation. +A polynomial of degree 4 like W(t) is uniquely determined by values +known at 5 different points. The points are arbitrary and can be chosen +to make the linear equations come out with a convenient set of steps for +quickly isolating the w[i]. + + Squaring follows the same procedure as multiplication, but there's +only one X(t) and it's evaluated at the 5 points, and those values +squared to give values of W(t). The interpolation is then identical, +and in fact the same 'toom_interpolate_5pts' subroutine is used for both +squaring and multiplying. + + Toom-3 is asymptotically O(N^1.465), the exponent being +log(5)/log(3), representing 5 recursive multiplies of 1/3 the original +size each. This is an improvement over Karatsuba at O(N^1.585), though +Toom does more work in the evaluation and interpolation and so it only +realizes its advantage above a certain size. + + Near the crossover between Toom-3 and Karatsuba there's generally a +range of sizes where the difference between the two is small. +'MUL_TOOM33_THRESHOLD' is a somewhat arbitrary point in that range and +successive runs of the tune program can give different values due to +small variations in measuring. A graph of time versus size for the two +shows the effect, see 'tune/README'. + + At the fairly small sizes where the Toom-3 thresholds occur it's +worth remembering that the asymptotic behaviour for Karatsuba and Toom-3 +can't be expected to make accurate predictions, due of course to the big +influence of all sorts of overheads, and the fact that only a few +recursions of each are being performed. Even at large sizes there's a +good chance machine dependent effects like cache architecture will mean +actual performance deviates from what might be predicted. + + The formula given for the Karatsuba algorithm (*note Karatsuba +Multiplication::) has an equivalent for Toom-3 involving only five +multiplies, but this would be complicated and unenlightening. + + An alternate view of Toom-3 can be found in Zuras (*note +References::), using a vector to represent the x and y splits and a +matrix multiplication for the evaluation and interpolation stages. The +matrix inverses are not meant to be actually used, and they have +elements with values much greater than in fact arise in the +interpolation steps. The diagram shown for the 3-way is attractive, but +again doesn't have to be implemented that way and for example with a bit +of rearrangement just one division by 6 can be done. + + +File: gmp.info, Node: Toom 4-Way Multiplication, Next: Higher degree Toom'n'half, Prev: Toom 3-Way Multiplication, Up: Multiplication Algorithms + +15.1.4 Toom 4-Way Multiplication +-------------------------------- + +Karatsuba and Toom-3 split the operands into 2 and 3 coefficients, +respectively. Toom-4 analogously splits the operands into 4 +coefficients. Using the notation from the section on Toom-3 +multiplication, we form two polynomials: + + X(t) = x3*t^3 + x2*t^2 + x1*t + x0 + Y(t) = y3*t^3 + y2*t^2 + y1*t + y0 + + X(t) and Y(t) are evaluated and multiplied at 7 points, giving values +of W(t) at those points. In GMP the following points are used, + + Point Value + t=0 x0 * y0, which gives w0 immediately + t=1/2 (x3+2*x2+4*x1+8*x0) * (y3+2*y2+4*y1+8*y0) + t=-1/2 (-x3+2*x2-4*x1+8*x0) * (-y3+2*y2-4*y1+8*y0) + t=1 (x3+x2+x1+x0) * (y3+y2+y1+y0) + t=-1 (-x3+x2-x1+x0) * (-y3+y2-y1+y0) + t=2 (8*x3+4*x2+2*x1+x0) * (8*y3+4*y2+2*y1+y0) + t=inf x3 * y3, which gives w6 immediately + + The number of additions and subtractions for Toom-4 is much larger +than for Toom-3. But several subexpressions occur multiple times, for +example x2+x0 occurs for both t=1 and t=-1. + + Toom-4 is asymptotically O(N^1.404), the exponent being +log(7)/log(4), representing 7 recursive multiplies of 1/4 the original +size each. + + +File: gmp.info, Node: Higher degree Toom'n'half, Next: FFT Multiplication, Prev: Toom 4-Way Multiplication, Up: Multiplication Algorithms + +15.1.5 Higher degree Toom'n'half +-------------------------------- + +The Toom algorithms described above (*note Toom 3-Way Multiplication::, +*note Toom 4-Way Multiplication::) generalize to split into an arbitrary +number of pieces. In general a split of two equally long operands into +r pieces leads to evaluations and pointwise multiplications done at +2*r-1 points. To fully exploit symmetries it would be better to have a +multiple of 4 points, that's why for higher degree Toom'n'half is used. + + Toom'n'half means that the existence of one more piece is considered +for a single operand. It can be virtual, i.e. zero, or real, when the +two operands are not exactly balanced. By choosing an even r, +Toom-r+1/2 requires 2r points, a multiple of four. + + The quadruplets of points include 0, inf, +1, and +-2^i, +-2^-i. +Each of them giving shortcuts for the evaluation phase and for some +steps in the interpolation phase. Further tricks are used to reduce the +memory footprint of the whole multiplication algorithm to a memory +buffer equal in size to the result of the product. + + Current GMP uses both Toom-6'n'half and Toom-8'n'half. + + +File: gmp.info, Node: FFT Multiplication, Next: Other Multiplication, Prev: Higher degree Toom'n'half, Up: Multiplication Algorithms + +15.1.6 FFT Multiplication +------------------------- + +At large to very large sizes a Fermat style FFT multiplication is used, +following Schönhage and Strassen (*note References::). Descriptions of +FFTs in various forms can be found in many textbooks, for instance Knuth +section 4.3.3 part C or Lipson chapter IX. A brief description of the +form used in GMP is given here. + + The multiplication done is x*y mod 2^N+1, for a given N. A full +product x*y is obtained by choosing N>=bits(x)+bits(y) and padding x and +y with high zero limbs. The modular product is the native form for the +algorithm, so padding to get a full product is unavoidable. + + The algorithm follows a split, evaluate, pointwise multiply, +interpolate and combine similar to that described above for Karatsuba +and Toom-3. A k parameter controls the split, with an FFT-k splitting +into 2^k pieces of M=N/2^k bits each. N must be a multiple of +(2^k)*mp_bits_per_limb so the split falls on limb boundaries, avoiding +bit shifts in the split and combine stages. + + The evaluations, pointwise multiplications, and interpolation are all +done modulo 2^N'+1 where N' is 2M+k+3 rounded up to a multiple of 2^k +and of 'mp_bits_per_limb'. The results of interpolation will be the +following negacyclic convolution of the input pieces, and the choice of +N' ensures these sums aren't truncated. + + --- + \ b + w[n] = / (-1) * x[i] * y[j] + --- + i+j==b*2^k+n + b=0,1 + + The points used for the evaluation are g^i for i=0 to 2^k-1 where +g=2^(2N'/2^k). g is a 2^k'th root of unity mod 2^N'+1, which produces +necessary cancellations at the interpolation stage, and it's also a +power of 2 so the fast Fourier transforms used for the evaluation and +interpolation do only shifts, adds and negations. + + The pointwise multiplications are done modulo 2^N'+1 and either +recurse into a further FFT or use a plain multiplication (Toom-3, +Karatsuba or basecase), whichever is optimal at the size N'. The +interpolation is an inverse fast Fourier transform. The resulting set +of sums of x[i]*y[j] are added at appropriate offsets to give the final +result. + + Squaring is the same, but x is the only input so it's one transform +at the evaluate stage and the pointwise multiplies are squares. The +interpolation is the same. + + For a mod 2^N+1 product, an FFT-k is an O(N^(k/(k-1))) algorithm, the +exponent representing 2^k recursed modular multiplies each 1/2^(k-1) the +size of the original. Each successive k is an asymptotic improvement, +but overheads mean each is only faster at bigger and bigger sizes. In +the code, 'MUL_FFT_TABLE' and 'SQR_FFT_TABLE' are the thresholds where +each k is used. Each new k effectively swaps some multiplying for some +shifts, adds and overheads. + + A mod 2^N+1 product can be formed with a normal NxN->2N bit multiply +plus a subtraction, so an FFT and Toom-3 etc can be compared directly. +A k=4 FFT at O(N^1.333) can be expected to be the first faster than +Toom-3 at O(N^1.465). In practice this is what's found, with +'MUL_FFT_MODF_THRESHOLD' and 'SQR_FFT_MODF_THRESHOLD' being between 300 +and 1000 limbs, depending on the CPU. So far it's been found that only +very large FFTs recurse into pointwise multiplies above these sizes. + + When an FFT is to give a full product, the change of N to 2N doesn't +alter the theoretical complexity for a given k, but for the purposes of +considering where an FFT might be first used it can be assumed that the +FFT is recursing into a normal multiply and that on that basis it's +doing 2^k recursed multiplies each 1/2^(k-2) the size of the inputs, +making it O(N^(k/(k-2))). This would mean k=7 at O(N^1.4) would be the +first FFT faster than Toom-3. In practice 'MUL_FFT_THRESHOLD' and +'SQR_FFT_THRESHOLD' have been found to be in the k=8 range, somewhere +between 3000 and 10000 limbs. + + The way N is split into 2^k pieces and then 2M+k+3 is rounded up to a +multiple of 2^k and 'mp_bits_per_limb' means that when +2^k>=mp\_bits\_per\_limb the effective N is a multiple of 2^(2k-1) bits. +The +k+3 means some values of N just under such a multiple will be +rounded to the next. The complexity calculations above assume that a +favourable size is used, meaning one which isn't padded through +rounding, and it's also assumed that the extra +k+3 bits are negligible +at typical FFT sizes. + + The practical effect of the 2^(2k-1) constraint is to introduce a +step-effect into measured speeds. For example k=8 will round N up to a +multiple of 32768 bits, so for a 32-bit limb there'll be 512 limb groups +of sizes for which 'mpn_mul_n' runs at the same speed. Or for k=9 +groups of 2048 limbs, k=10 groups of 8192 limbs, etc. In practice it's +been found each k is used at quite small multiples of its size +constraint and so the step effect is quite noticeable in a time versus +size graph. + + The threshold determinations currently measure at the mid-points of +size steps, but this is sub-optimal since at the start of a new step it +can happen that it's better to go back to the previous k for a while. +Something more sophisticated for 'MUL_FFT_TABLE' and 'SQR_FFT_TABLE' +will be needed. + + +File: gmp.info, Node: Other Multiplication, Next: Unbalanced Multiplication, Prev: FFT Multiplication, Up: Multiplication Algorithms + +15.1.7 Other Multiplication +--------------------------- + +The Toom algorithms described above (*note Toom 3-Way Multiplication::, +*note Toom 4-Way Multiplication::) generalizes to split into an +arbitrary number of pieces, as per Knuth section 4.3.3 algorithm C. +This is not currently used. The notes here are merely for interest. + + In general a split into r+1 pieces is made, and evaluations and +pointwise multiplications done at 2*r+1 points. A 4-way split does 7 +pointwise multiplies, 5-way does 9, etc. Asymptotically an (r+1)-way +algorithm is O(N^(log(2*r+1)/log(r+1))). Only the pointwise +multiplications count towards big-O complexity, but the time spent in +the evaluate and interpolate stages grows with r and has a significant +practical impact, with the asymptotic advantage of each r realized only +at bigger and bigger sizes. The overheads grow as O(N*r), whereas in an +r=2^k FFT they grow only as O(N*log(r)). + + Knuth algorithm C evaluates at points 0,1,2,...,2*r, but exercise 4 +uses -r,...,0,...,r and the latter saves some small multiplies in the +evaluate stage (or rather trades them for additions), and has a further +saving of nearly half the interpolate steps. The idea is to separate +odd and even final coefficients and then perform algorithm C steps C7 +and C8 on them separately. The divisors at step C7 become j^2 and the +multipliers at C8 become 2*t*j-j^2. + + Splitting odd and even parts through positive and negative points can +be thought of as using -1 as a square root of unity. If a 4th root of +unity was available then a further split and speedup would be possible, +but no such root exists for plain integers. Going to complex integers +with i=sqrt(-1) doesn't help, essentially because in Cartesian form it +takes three real multiplies to do a complex multiply. The existence of +2^k'th roots of unity in a suitable ring or field lets the fast Fourier +transform keep splitting and get to O(N*log(r)). + + Floating point FFTs use complex numbers approximating Nth roots of +unity. Some processors have special support for such FFTs. But these +are not used in GMP since it's very difficult to guarantee an exact +result (to some number of bits). An occasional difference of 1 in the +last bit might not matter to a typical signal processing algorithm, but +is of course of vital importance to GMP. + + +File: gmp.info, Node: Unbalanced Multiplication, Prev: Other Multiplication, Up: Multiplication Algorithms + +15.1.8 Unbalanced Multiplication +-------------------------------- + +Multiplication of operands with different sizes, both below +'MUL_TOOM22_THRESHOLD' are done with plain schoolbook multiplication +(*note Basecase Multiplication::). + + For really large operands, we invoke FFT directly. + + For operands between these sizes, we use Toom inspired algorithms +suggested by Alberto Zanoni and Marco Bodrato. The idea is to split the +operands into polynomials of different degree. GMP currently splits the +smaller operand into 2 coefficients, i.e., a polynomial of degree 1, but +the larger operand can be split into 2, 3, or 4 coefficients, i.e., a +polynomial of degree 1 to 3. + + +File: gmp.info, Node: Division Algorithms, Next: Greatest Common Divisor Algorithms, Prev: Multiplication Algorithms, Up: Algorithms + +15.2 Division Algorithms +======================== + +* Menu: + +* Single Limb Division:: +* Basecase Division:: +* Divide and Conquer Division:: +* Block-Wise Barrett Division:: +* Exact Division:: +* Exact Remainder:: +* Small Quotient Division:: + + +File: gmp.info, Node: Single Limb Division, Next: Basecase Division, Prev: Division Algorithms, Up: Division Algorithms + +15.2.1 Single Limb Division +--------------------------- + +Nx1 division is implemented using repeated 2x1 divisions from high to +low, either with a hardware divide instruction or a multiplication by +inverse, whichever is best on a given CPU. + + The multiply by inverse follows "Improved division by invariant +integers" by Möller and Granlund (*note References::) and is implemented +as 'udiv_qrnnd_preinv' in 'gmp-impl.h'. The idea is to have a +fixed-point approximation to 1/d (see 'invert_limb') and then multiply +by the high limb (plus one bit) of the dividend to get a quotient q. +With d normalized (high bit set), q is no more than 1 too small. +Subtracting q*d from the dividend gives a remainder, and reveals whether +q or q-1 is correct. + + The result is a division done with two multiplications and four or +five arithmetic operations. On CPUs with low latency multipliers this +can be much faster than a hardware divide, though the cost of +calculating the inverse at the start may mean it's only better on inputs +bigger than say 4 or 5 limbs. + + When a divisor must be normalized, either for the generic C +'__udiv_qrnnd_c' or the multiply by inverse, the division performed is +actually a*2^k by d*2^k where a is the dividend and k is the power +necessary to have the high bit of d*2^k set. The bit shifts for the +dividend are usually accomplished "on the fly" meaning by extracting the +appropriate bits at each step. Done this way the quotient limbs come +out aligned ready to store. When only the remainder is wanted, an +alternative is to take the dividend limbs unshifted and calculate r = a +mod d*2^k followed by an extra final step r*2^k mod d*2^k. This can +help on CPUs with poor bit shifts or few registers. + + The multiply by inverse can be done two limbs at a time. The +calculation is basically the same, but the inverse is two limbs and the +divisor treated as if padded with a low zero limb. This means more +work, since the inverse will need a 2x2 multiply, but the four 1x1s to +do that are independent and can therefore be done partly or wholly in +parallel. Likewise for a 2x1 calculating q*d. The net effect is to +process two limbs with roughly the same two multiplies worth of latency +that one limb at a time gives. This extends to 3 or 4 limbs at a time, +though the extra work to apply the inverse will almost certainly soon +reach the limits of multiplier throughput. + + A similar approach in reverse can be taken to process just half a +limb at a time if the divisor is only a half limb. In this case the 1x1 +multiply for the inverse effectively becomes two (1/2)x1 for each limb, +which can be a saving on CPUs with a fast half limb multiply, or in fact +if the only multiply is a half limb, and especially if it's not +pipelined. + + +File: gmp.info, Node: Basecase Division, Next: Divide and Conquer Division, Prev: Single Limb Division, Up: Division Algorithms + +15.2.2 Basecase Division +------------------------ + +Basecase NxM division is like long division done by hand, but in base +2^mp_bits_per_limb. See Knuth section 4.3.1 algorithm D, and +'mpn/generic/sb_divrem_mn.c'. + + Briefly stated, while the dividend remains larger than the divisor, a +high quotient limb is formed and the Nx1 product q*d subtracted at the +top end of the dividend. With a normalized divisor (most significant +bit set), each quotient limb can be formed with a 2x1 division and a 1x1 +multiplication plus some subtractions. The 2x1 division is by the high +limb of the divisor and is done either with a hardware divide or a +multiply by inverse (the same as in *note Single Limb Division::) +whichever is faster. Such a quotient is sometimes one too big, +requiring an addback of the divisor, but that happens rarely. + + With Q=N-M being the number of quotient limbs, this is an O(Q*M) +algorithm and will run at a speed similar to a basecase QxM +multiplication, differing in fact only in the extra multiply and divide +for each of the Q quotient limbs. + diff --git a/gmp-6.3.0/doc/gmp.info-2 b/gmp-6.3.0/doc/gmp.info-2 new file mode 100644 index 0000000..af839fb --- /dev/null +++ b/gmp-6.3.0/doc/gmp.info-2 @@ -0,0 +1,4104 @@ +This is gmp.info, produced by makeinfo version 6.7 from gmp.texi. + +This manual describes how to install and use the GNU multiple precision +arithmetic library, version 6.3.0. + + Copyright 1991, 1993-2016, 2018-2020 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and +with the Back-Cover Texts being "You have freedom to copy and modify +this GNU Manual, like GNU software". A copy of the license is included +in *note GNU Free Documentation License::. +INFO-DIR-SECTION GNU libraries +START-INFO-DIR-ENTRY +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +END-INFO-DIR-ENTRY + + +File: gmp.info, Node: Divide and Conquer Division, Next: Block-Wise Barrett Division, Prev: Basecase Division, Up: Division Algorithms + +15.2.3 Divide and Conquer Division +---------------------------------- + +For divisors larger than 'DC_DIV_QR_THRESHOLD', division is done by +dividing. Or to be precise by a recursive divide and conquer algorithm +based on work by Moenck and Borodin, Jebelean, and Burnikel and Ziegler +(*note References::). + + The algorithm consists essentially of recognising that a 2NxN +division can be done with the basecase division algorithm (*note +Basecase Division::), but using N/2 limbs as a base, not just a single +limb. This way the multiplications that arise are (N/2)x(N/2) and can +take advantage of Karatsuba and higher multiplication algorithms (*note +Multiplication Algorithms::). The two "digits" of the quotient are +formed by recursive Nx(N/2) divisions. + + If the (N/2)x(N/2) multiplies are done with a basecase multiplication +then the work is about the same as a basecase division, but with more +function call overheads and with some subtractions separated from the +multiplies. These overheads mean that it's only when N/2 is above +'MUL_TOOM22_THRESHOLD' that divide and conquer is of use. + + 'DC_DIV_QR_THRESHOLD' is based on the divisor size N, so it will be +somewhere above twice 'MUL_TOOM22_THRESHOLD', but how much above depends +on the CPU. An optimized 'mpn_mul_basecase' can lower +'DC_DIV_QR_THRESHOLD' a little by offering a ready-made advantage over +repeated 'mpn_submul_1' calls. + + Divide and conquer is asymptotically O(M(N)*log(N)) where M(N) is the +time for an NxN multiplication done with FFTs. The actual time is a sum +over multiplications of the recursed sizes, as can be seen near the end +of section 2.2 of Burnikel and Ziegler. For example, within the Toom-3 +range, divide and conquer is 2.63*M(N). With higher algorithms the M(N) +term improves and the multiplier tends to log(N). In practice, at +moderate to large sizes, a 2NxN division is about 2 to 4 times slower +than an NxN multiplication. + + +File: gmp.info, Node: Block-Wise Barrett Division, Next: Exact Division, Prev: Divide and Conquer Division, Up: Division Algorithms + +15.2.4 Block-Wise Barrett Division +---------------------------------- + +For the largest divisions, a block-wise Barrett division algorithm is +used. Here, the divisor is inverted to a precision determined by the +relative size of the dividend and divisor. Blocks of quotient limbs are +then generated by multiplying blocks from the dividend by the inverse. + + Our block-wise algorithm computes a smaller inverse than in the plain +Barrett algorithm. For a 2n/n division, the inverse will be just +ceil(n/2) limbs. + + +File: gmp.info, Node: Exact Division, Next: Exact Remainder, Prev: Block-Wise Barrett Division, Up: Division Algorithms + +15.2.5 Exact Division +--------------------- + +A so-called exact division is when the dividend is known to be an exact +multiple of the divisor. Jebelean's exact division algorithm uses this +knowledge to make some significant optimizations (*note References::). + + The idea can be illustrated in decimal for example with 368154 +divided by 543. Because the low digit of the dividend is 4, the low +digit of the quotient must be 8. This is arrived at from 4*7 mod 10, +using the fact 7 is the modular inverse of 3 (the low digit of the +divisor), since 3*7 == 1 mod 10. So 8*543=4344 can be subtracted from +the dividend leaving 363810. Notice the low digit has become zero. + + The procedure is repeated at the second digit, with the next quotient +digit 7 (7 == 1*7 mod 10), subtracting 7*543=3801, leaving 325800. And +finally at the third digit with quotient digit 6 (8*7 mod 10), +subtracting 6*543=3258 leaving 0. So the quotient is 678. + + Notice however that the multiplies and subtractions don't need to +extend past the low three digits of the dividend, since that's enough to +determine the three quotient digits. For the last quotient digit no +subtraction is needed at all. On a 2NxN division like this one, only +about half the work of a normal basecase division is necessary. + + For an NxM exact division producing Q=N-M quotient limbs, the saving +over a normal basecase division is in two parts. Firstly, each of the Q +quotient limbs needs only one multiply, not a 2x1 divide and multiply. +Secondly, the crossproducts are reduced when Q>M to Q*M-M*(M+1)/2, or +when Q<=M to Q*(Q-1)/2. Notice the savings are complementary. If Q is +big then many divisions are saved, or if Q is small then the +crossproducts reduce to a small number. + + The modular inverse used is calculated efficiently by 'binvert_limb' +in 'gmp-impl.h'. This does four multiplies for a 32-bit limb, or six +for a 64-bit limb. 'tune/modlinv.c' has some alternate implementations +that might suit processors better at bit twiddling than multiplying. + + The sub-quadratic exact division described by Jebelean in "Exact +Division with Karatsuba Complexity" is not currently implemented. It +uses a rearrangement similar to the divide and conquer for normal +division (*note Divide and Conquer Division::), but operating from low +to high. A further possibility not currently implemented is +"Bidirectional Exact Integer Division" by Krandick and Jebelean which +forms quotient limbs from both the high and low ends of the dividend, +and can halve once more the number of crossproducts needed in a 2NxN +division. + + A special case exact division by 3 exists in 'mpn_divexact_by3', +supporting Toom-3 multiplication and 'mpq' canonicalizations. It forms +quotient digits with a multiply by the modular inverse of 3 (which is +'0xAA..AAB') and uses two comparisons to determine a borrow for the next +limb. The multiplications don't need to be on the dependent chain, as +long as the effect of the borrows is applied, which can help chips with +pipelined multipliers. + + +File: gmp.info, Node: Exact Remainder, Next: Small Quotient Division, Prev: Exact Division, Up: Division Algorithms + +15.2.6 Exact Remainder +---------------------- + +If the exact division algorithm is done with a full subtraction at each +stage and the dividend isn't a multiple of the divisor, then low zero +limbs are produced but with a remainder in the high limbs. For dividend +a, divisor d, quotient q, and b = 2^mp_bits_per_limb, this remainder r +is of the form + + a = q*d + r*b^n + + n represents the number of zero limbs produced by the subtractions, +that being the number of limbs produced for q. r will be in the range +0<=rb*r+u2 condition appropriately relaxed. + + +File: gmp.info, Node: Greatest Common Divisor Algorithms, Next: Powering Algorithms, Prev: Division Algorithms, Up: Algorithms + +15.3 Greatest Common Divisor +============================ + +* Menu: + +* Binary GCD:: +* Lehmer's Algorithm:: +* Subquadratic GCD:: +* Extended GCD:: +* Jacobi Symbol:: + + +File: gmp.info, Node: Binary GCD, Next: Lehmer's Algorithm, Prev: Greatest Common Divisor Algorithms, Up: Greatest Common Divisor Algorithms + +15.3.1 Binary GCD +----------------- + +At small sizes GMP uses an O(N^2) binary style GCD. This is described +in many textbooks, for example Knuth section 4.5.2 algorithm B. It +simply consists of successively reducing odd operands a and b using + + a,b = abs(a-b),min(a,b) + strip factors of 2 from a + + The Euclidean GCD algorithm, as per Knuth algorithms E and A, +repeatedly computes the quotient q = floor(a/b) and replaces a,b by v, u +- q v. The binary algorithm has so far been found to be faster than the +Euclidean algorithm everywhere. One reason the binary method does well +is that the implied quotient at each step is usually small, so often +only one or two subtractions are needed to get the same effect as a +division. Quotients 1, 2 and 3 for example occur 67.7% of the time, see +Knuth section 4.5.3 Theorem E. + + When the implied quotient is large, meaning b is much smaller than a, +then a division is worthwhile. This is the basis for the initial a mod +b reductions in 'mpn_gcd' and 'mpn_gcd_1' (the latter for both Nx1 and +1x1 cases). But after that initial reduction, big quotients occur too +rarely to make it worth checking for them. + + + The final 1x1 GCD in 'mpn_gcd_1' is done in the generic C code as +described above. For two N-bit operands, the algorithm takes about 0.68 +iterations per bit. For optimum performance some attention needs to be +paid to the way the factors of 2 are stripped from a. + + Firstly it may be noted that in two's complement the number of low +zero bits on a-b is the same as b-a, so counting or testing can begin on +a-b without waiting for abs(a-b) to be determined. + + A loop stripping low zero bits tends not to branch predict well, +since the condition is data dependent. But on average there's only a +few low zeros, so an option is to strip one or two bits arithmetically +then loop for more (as done for AMD K6). Or use a lookup table to get a +count for several bits then loop for more (as done for AMD K7). An +alternative approach is to keep just one of a and b odd and iterate + + a,b = abs(a-b), min(a,b) + a = a/2 if even + b = b/2 if even + + This requires about 1.25 iterations per bit, but stripping of a +single bit at each step avoids any branching. Repeating the bit strip +reduces to about 0.9 iterations per bit, which may be a worthwhile +tradeoff. + + Generally with the above approaches a speed of perhaps 6 cycles per +bit can be achieved, which is still not terribly fast with for instance +a 64-bit GCD taking nearly 400 cycles. It's this sort of time which +means it's not usually advantageous to combine a set of divisibility +tests into a GCD. + + Currently, the binary algorithm is used for GCD only when N < 3. + + +File: gmp.info, Node: Lehmer's Algorithm, Next: Subquadratic GCD, Prev: Binary GCD, Up: Greatest Common Divisor Algorithms + +15.3.2 Lehmer's algorithm +------------------------- + +Lehmer's improvement of the Euclidean algorithms is based on the +observation that the initial part of the quotient sequence depends only +on the most significant parts of the inputs. The variant of Lehmer's +algorithm used in GMP splits off the most significant two limbs, as +suggested, e.g., in "A Double-Digit Lehmer-Euclid Algorithm" by Jebelean +(*note References::). The quotients of two double-limb inputs are +collected as a 2 by 2 matrix with single-limb elements. This is done by +the function 'mpn_hgcd2'. The resulting matrix is applied to the inputs +using 'mpn_mul_1' and 'mpn_submul_1'. Each iteration usually reduces +the inputs by almost one limb. In the rare case of a large quotient, no +progress can be made by examining just the most significant two limbs, +and the quotient is computed using plain division. + + The resulting algorithm is asymptotically O(N^2), just as the +Euclidean algorithm and the binary algorithm. The quadratic part of the +work are the calls to 'mpn_mul_1' and 'mpn_submul_1'. For small sizes, +the linear work is also significant. There are roughly N calls to the +'mpn_hgcd2' function. This function uses a couple of important +optimizations: + + * It uses the same relaxed notion of correctness as 'mpn_hgcd' (see + next section). This means that when called with the most + significant two limbs of two large numbers, the returned matrix + does not always correspond exactly to the initial quotient sequence + for the two large numbers; the final quotient may sometimes be one + off. + + * It takes advantage of the fact that the quotients are usually + small. The division operator is not used, since the corresponding + assembler instruction is very slow on most architectures. (This + code could probably be improved further, it uses many branches that + are unfriendly to prediction.) + + * It switches from double-limb calculations to single-limb + calculations half-way through, when the input numbers have been + reduced in size from two limbs to one and a half. + + +File: gmp.info, Node: Subquadratic GCD, Next: Extended GCD, Prev: Lehmer's Algorithm, Up: Greatest Common Divisor Algorithms + +15.3.3 Subquadratic GCD +----------------------- + +For inputs larger than 'GCD_DC_THRESHOLD', GCD is computed via the HGCD +(Half GCD) function, as a generalization to Lehmer's algorithm. + + Let the inputs a,b be of size N limbs each. Put S = floor(N/2) + 1. +Then HGCD(a,b) returns a transformation matrix T with non-negative +elements, and reduced numbers (c;d) = T^{-1} (a;b). The reduced numbers +c,d must be larger than S limbs, while their difference abs(c-d) must +fit in S limbs. The matrix elements will also be of size roughly N/2. + + The HGCD base case uses Lehmer's algorithm, but with the above stop +condition that returns reduced numbers and the corresponding +transformation matrix half-way through. For inputs larger than +'HGCD_THRESHOLD', HGCD is computed recursively, using the divide and +conquer algorithm in "On Schönhage's algorithm and subquadratic integer +GCD computation" by Möller (*note References::). The recursive +algorithm consists of these main steps. + + * Call HGCD recursively, on the most significant N/2 limbs. Apply + the resulting matrix T_1 to the full numbers, reducing them to a + size just above 3N/2. + + * Perform a small number of division or subtraction steps to reduce + the numbers to size below 3N/2. This is essential mainly for the + unlikely case of large quotients. + + * Call HGCD recursively, on the most significant N/2 limbs of the + reduced numbers. Apply the resulting matrix T_2 to the full + numbers, reducing them to a size just above N/2. + + * Compute T = T_1 T_2. + + * Perform a small number of division and subtraction steps to satisfy + the requirements, and return. + + GCD is then implemented as a loop around HGCD, similarly to Lehmer's +algorithm. Where Lehmer repeatedly chops off the top two limbs, calls +'mpn_hgcd2', and applies the resulting matrix to the full numbers, the +sub-quadratic GCD chops off the most significant third of the limbs (the +proportion is a tuning parameter, and 1/3 seems to be more efficient +than, e.g., 1/2), calls 'mpn_hgcd', and applies the resulting matrix. +Once the input numbers are reduced to size below 'GCD_DC_THRESHOLD', +Lehmer's algorithm is used for the rest of the work. + + The asymptotic running time of both HGCD and GCD is O(M(N)*log(N)), +where M(N) is the time for multiplying two N-limb numbers. + + +File: gmp.info, Node: Extended GCD, Next: Jacobi Symbol, Prev: Subquadratic GCD, Up: Greatest Common Divisor Algorithms + +15.3.4 Extended GCD +------------------- + +The extended GCD function, or GCDEXT, calculates gcd(a,b) and also +cofactors x and y satisfying a*x+b*y=gcd(a,b). All the algorithms used +for plain GCD are extended to handle this case. The binary algorithm is +used only for single-limb GCDEXT. Lehmer's algorithm is used for sizes +up to 'GCDEXT_DC_THRESHOLD'. Above this threshold, GCDEXT is +implemented as a loop around HGCD, but with more book-keeping to keep +track of the cofactors. This gives the same asymptotic running time as +for GCD and HGCD, O(M(N)*log(N)). + + One difference to plain GCD is that while the inputs a and b are +reduced as the algorithm proceeds, the cofactors x and y grow in size. +This makes the tuning of the chopping-point more difficult. The current +code chops off the most significant half of the inputs for the call to +HGCD in the first iteration, and the most significant two thirds for the +remaining calls. This strategy could surely be improved. Also the stop +condition for the loop, where Lehmer's algorithm is invoked once the +inputs are reduced below 'GCDEXT_DC_THRESHOLD', could maybe be improved +by taking into account the current size of the cofactors. + + +File: gmp.info, Node: Jacobi Symbol, Prev: Extended GCD, Up: Greatest Common Divisor Algorithms + +15.3.5 Jacobi Symbol +-------------------- + +Jacobi symbol (A/B) + + Initially if either operand fits in a single limb, a reduction is +done with either 'mpn_mod_1' or 'mpn_modexact_1_odd', followed by the +binary algorithm on a single limb. The binary algorithm is well suited +to a single limb, and the whole calculation in this case is quite +efficient. + + For inputs larger than 'GCD_DC_THRESHOLD', 'mpz_jacobi', +'mpz_legendre' and 'mpz_kronecker' are computed via the HGCD (Half GCD) +function, as a generalization to Lehmer's algorithm. + + Most GCD algorithms reduce a and b by repeatedly computing the +quotient q = floor(a/b) and iteratively replacing + + a, b = b, a - q * b + + Different algorithms use different methods for calculating q, but the +core algorithm is the same if we use *note Lehmer's Algorithm:: or *note +HGCD: Subquadratic GCD. + + At each step it is possible to compute if the reduction inverts the +Jacobi symbol based on the two least significant bits of A and B. For +more details see "Efficient computation of the Jacobi symbol" by Möller +(*note References::). + + A small set of bits is thus used to track state + * current sign of result (1 bit) + + * two least significant bits of A and B (4 bits) + + * a pointer to which input is currently the denominator (1 bit) + + In all the routines sign changes for the result are accumulated using +fast bit twiddling which avoids conditional jumps. + + The final result is calculated after verifying the inputs are coprime +(GCD = 1) by raising (-1)^e. + + Much of the HGCD code is shared directly with the HGCD +implementations, such as the 2x2 matrix calculation, *Note Lehmer's +Algorithm:: basecase and 'GCD_DC_THRESHOLD'. + + The asymptotic running time is O(M(N)*log(N)), where M(N) is the time +for multiplying two N-limb numbers. + + +File: gmp.info, Node: Powering Algorithms, Next: Root Extraction Algorithms, Prev: Greatest Common Divisor Algorithms, Up: Algorithms + +15.4 Powering Algorithms +======================== + +* Menu: + +* Normal Powering Algorithm:: +* Modular Powering Algorithm:: + + +File: gmp.info, Node: Normal Powering Algorithm, Next: Modular Powering Algorithm, Prev: Powering Algorithms, Up: Powering Algorithms + +15.4.1 Normal Powering +---------------------- + +Normal 'mpz' or 'mpf' powering uses a simple binary algorithm, +successively squaring and then multiplying by the base when a 1 bit is +seen in the exponent, as per Knuth section 4.6.3. The "left to right" +variant described there is used rather than algorithm A, since it's just +as easy and can be done with somewhat less temporary memory. + + +File: gmp.info, Node: Modular Powering Algorithm, Prev: Normal Powering Algorithm, Up: Powering Algorithms + +15.4.2 Modular Powering +----------------------- + +Modular powering is implemented using a 2^k-ary sliding window +algorithm, as per "Handbook of Applied Cryptography" algorithm 14.85 +(*note References::). k is chosen according to the size of the +exponent. Larger exponents use larger values of k, the choice being +made to minimize the average number of multiplications that must +supplement the squaring. + + The modular multiplies and squarings use either a simple division or +the REDC method by Montgomery (*note References::). REDC is a little +faster, essentially saving N single limb divisions in a fashion similar +to an exact remainder (*note Exact Remainder::). + + +File: gmp.info, Node: Root Extraction Algorithms, Next: Radix Conversion Algorithms, Prev: Powering Algorithms, Up: Algorithms + +15.5 Root Extraction Algorithms +=============================== + +* Menu: + +* Square Root Algorithm:: +* Nth Root Algorithm:: +* Perfect Square Algorithm:: +* Perfect Power Algorithm:: + + +File: gmp.info, Node: Square Root Algorithm, Next: Nth Root Algorithm, Prev: Root Extraction Algorithms, Up: Root Extraction Algorithms + +15.5.1 Square Root +------------------ + +Square roots are taken using the "Karatsuba Square Root" algorithm by +Paul Zimmermann (*note References::). + + An input n is split into four parts of k bits each, so with b=2^k we +have n = a3*b^3 + a2*b^2 + a1*b + a0. Part a3 must be "normalized" so +that either the high or second highest bit is set. In GMP, k is kept on +a limb boundary and the input is left shifted (by an even number of +bits) to normalize. + + The square root of the high two parts is taken, by recursive +application of the algorithm (bottoming out in a one-limb Newton's +method), + + s1,r1 = sqrtrem (a3*b + a2) + + This is an approximation to the desired root and is extended by a +division to give s,r, + + q,u = divrem (r1*b + a1, 2*s1) + s = s1*b + q + r = u*b + a0 - q^2 + + The normalization requirement on a3 means at this point s is either +correct or 1 too big. r is negative in the latter case, so + + if r < 0 then + r = r + 2*s - 1 + s = s - 1 + + The algorithm is expressed in a divide and conquer form, but as noted +in the paper it can also be viewed as a discrete variant of Newton's +method, or as a variation on the schoolboy method (no longer taught) for +square roots two digits at a time. + + If the remainder r is not required then usually only a few high limbs +of r and u need to be calculated to determine whether an adjustment to s +is required. This optimization is not currently implemented. + + In the Karatsuba multiplication range this algorithm is +O(1.5*M(N/2)), where M(n) is the time to multiply two numbers of n +limbs. In the FFT multiplication range this grows to a bound of +O(6*M(N/2)). In practice a factor of about 1.5 to 1.8 is found in the +Karatsuba and Toom-3 ranges, growing to 2 or 3 in the FFT range. + + The algorithm does all its calculations in integers and the resulting +'mpn_sqrtrem' is used for both 'mpz_sqrt' and 'mpf_sqrt'. The extended +precision given by 'mpf_sqrt_ui' is obtained by padding with zero limbs. + + +File: gmp.info, Node: Nth Root Algorithm, Next: Perfect Square Algorithm, Prev: Square Root Algorithm, Up: Root Extraction Algorithms + +15.5.2 Nth Root +--------------- + +Integer Nth roots are taken using Newton's method with the following +iteration, where A is the input and n is the root to be taken. + + 1 A + a[i+1] = - * ( --------- + (n-1)*a[i] ) + n a[i]^(n-1) + + The initial approximation a[1] is generated bitwise by successively +powering a trial root with or without new 1 bits, aiming to be just +above the true root. The iteration converges quadratically when started +from a good approximation. When n is large more initial bits are needed +to get good convergence. The current implementation is not particularly +well optimized. + + +File: gmp.info, Node: Perfect Square Algorithm, Next: Perfect Power Algorithm, Prev: Nth Root Algorithm, Up: Root Extraction Algorithms + +15.5.3 Perfect Square +--------------------- + +A significant fraction of non-squares can be quickly identified by +checking whether the input is a quadratic residue modulo small integers. + + 'mpz_perfect_square_p' first tests the input mod 256, which means +just examining the low byte. Only 44 different values occur for squares +mod 256, so 82.8% of inputs can be immediately identified as +non-squares. + + On a 32-bit system similar tests are done mod 9, 5, 7, 13 and 17, for +a total 99.25% of inputs identified as non-squares. On a 64-bit system +97 is tested too, for a total 99.62%. + + These moduli are chosen because they're factors of 2^24-1 (or 2^48-1 +for 64-bits), and such a remainder can be quickly taken just using +additions (see 'mpn_mod_34lsub1'). + + When nails are in use moduli are instead selected by the 'gen-psqr.c' +program and applied with an 'mpn_mod_1'. The same 2^24-1 or 2^48-1 +could be done with nails using some extra bit shifts, but this is not +currently implemented. + + In any case each modulus is applied to the 'mpn_mod_34lsub1' or +'mpn_mod_1' remainder and a table lookup identifies non-squares. By +using a "modexact" style calculation, and suitably permuted tables, just +one multiply each is required, see the code for details. Moduli are +also combined to save operations, so long as the lookup tables don't +become too big. 'gen-psqr.c' does all the pre-calculations. + + A square root must still be taken for any value that passes these +tests, to verify it's really a square and not one of the small fraction +of non-squares that get through (i.e. a pseudo-square to all the tested +bases). + + Clearly more residue tests could be done, 'mpz_perfect_square_p' only +uses a compact and efficient set. Big inputs would probably benefit +from more residue testing, small inputs might be better off with less. +The assumed distribution of squares versus non-squares in the input +would affect such considerations. + + +File: gmp.info, Node: Perfect Power Algorithm, Prev: Perfect Square Algorithm, Up: Root Extraction Algorithms + +15.5.4 Perfect Power +-------------------- + +Detecting perfect powers is required by some factorization algorithms. +Currently 'mpz_perfect_power_p' is implemented using repeated Nth root +extractions, though naturally only prime roots need to be considered. +(*Note Nth Root Algorithm::.) + + If a prime divisor p with multiplicity e can be found, then only +roots which are divisors of e need to be considered, much reducing the +work necessary. To this end divisibility by a set of small primes is +checked. + + +File: gmp.info, Node: Radix Conversion Algorithms, Next: Other Algorithms, Prev: Root Extraction Algorithms, Up: Algorithms + +15.6 Radix Conversion +===================== + +Radix conversions are less important than other algorithms. A program +dominated by conversions should probably use a different data +representation. + +* Menu: + +* Binary to Radix:: +* Radix to Binary:: + + +File: gmp.info, Node: Binary to Radix, Next: Radix to Binary, Prev: Radix Conversion Algorithms, Up: Radix Conversion Algorithms + +15.6.1 Binary to Radix +---------------------- + +Conversions from binary to a power-of-2 radix use a simple and fast O(N) +bit extraction algorithm. + + Conversions from binary to other radices use one of two algorithms. +Sizes below 'GET_STR_PRECOMPUTE_THRESHOLD' use a basic O(N^2) method. +Repeated divisions by b^n are made, where b is the radix and n is the +biggest power that fits in a limb. But instead of simply using the +remainder r from such divisions, an extra divide step is done to give a +fractional limb representing r/b^n. The digits of r can then be +extracted using multiplications by b rather than divisions. Special +case code is provided for decimal, allowing multiplications by 10 to +optimize to shifts and adds. + + Above 'GET_STR_PRECOMPUTE_THRESHOLD' a sub-quadratic algorithm is +used. For an input t, powers b^(n*2^i) of the radix are calculated, +until a power between t and sqrt(t) is reached. t is then divided by +that largest power, giving a quotient which is the digits above that +power, and a remainder which is those below. These two parts are in +turn divided by the second highest power, and so on recursively. When a +piece has been divided down to less than 'GET_STR_DC_THRESHOLD' limbs, +the basecase algorithm described above is used. + + The advantage of this algorithm is that big divisions can make use of +the sub-quadratic divide and conquer division (*note Divide and Conquer +Division::), and big divisions tend to have less overheads than lots of +separate single limb divisions anyway. But in any case the cost of +calculating the powers b^(n*2^i) must first be overcome. + + 'GET_STR_PRECOMPUTE_THRESHOLD' and 'GET_STR_DC_THRESHOLD' represent +the same basic thing, the point where it becomes worth doing a big +division to cut the input in half. 'GET_STR_PRECOMPUTE_THRESHOLD' +includes the cost of calculating the radix power required, whereas +'GET_STR_DC_THRESHOLD' assumes that's already available, which is the +case when recursing. + + Since the base case produces digits from least to most significant +but they want to be stored from most to least, it's necessary to +calculate in advance how many digits there will be, or at least be sure +not to underestimate that. For GMP the number of input bits is +multiplied by 'chars_per_bit_exactly' from 'mp_bases', rounding up. The +result is either correct or one too big. + + Examining some of the high bits of the input could increase the +chance of getting the exact number of digits, but an exact result every +time would not be practical, since in general the difference between +numbers 100... and 99... is only in the last few bits and the work to +identify 99... might well be almost as much as a full conversion. + + The r/b^n scheme described above for using multiplications to bring +out digits might be useful for more than a single limb. Some brief +experiments with it on the base case when recursing didn't give a +noticeable improvement, but perhaps that was only due to the +implementation. Something similar would work for the sub-quadratic +divisions too, though there would be the cost of calculating a bigger +radix power. + + Another possible improvement for the sub-quadratic part would be to +arrange for radix powers that balanced the sizes of quotient and +remainder produced, i.e. the highest power would be an b^(n*k) +approximately equal to sqrt(t), not restricted to a 2^i factor. That +ought to smooth out a graph of times against sizes, but may or may not +be a net speedup. + + +File: gmp.info, Node: Radix to Binary, Prev: Binary to Radix, Up: Radix Conversion Algorithms + +15.6.2 Radix to Binary +---------------------- + +*This section needs to be rewritten, it currently describes the +algorithms used before GMP 4.3.* + + Conversions from a power-of-2 radix into binary use a simple and fast +O(N) bitwise concatenation algorithm. + + Conversions from other radices use one of two algorithms. Sizes +below 'SET_STR_PRECOMPUTE_THRESHOLD' use a basic O(N^2) method. Groups +of n digits are converted to limbs, where n is the biggest power of the +base b which will fit in a limb, then those groups are accumulated into +the result by multiplying by b^n and adding. This saves multi-precision +operations, as per Knuth section 4.4 part E (*note References::). Some +special case code is provided for decimal, giving the compiler a chance +to optimize multiplications by 10. + + Above 'SET_STR_PRECOMPUTE_THRESHOLD' a sub-quadratic algorithm is +used. First groups of n digits are converted into limbs. Then adjacent +limbs are combined into limb pairs with x*b^n+y, where x and y are the +limbs. Adjacent limb pairs are combined into quads similarly with +x*b^(2n)+y. This continues until a single block remains, that being the +result. + + The advantage of this method is that the multiplications for each x +are big blocks, allowing Karatsuba and higher algorithms to be used. +But the cost of calculating the powers b^(n*2^i) must be overcome. +'SET_STR_PRECOMPUTE_THRESHOLD' usually ends up quite big, around 5000 +digits, and on some processors much bigger still. + + 'SET_STR_PRECOMPUTE_THRESHOLD' is based on the input digits (and +tuned for decimal), though it might be better based on a limb count, so +as to be independent of the base. But that sort of count isn't used by +the base case and so would need some sort of initial calculation or +estimate. + + The main reason 'SET_STR_PRECOMPUTE_THRESHOLD' is so much bigger than +the corresponding 'GET_STR_PRECOMPUTE_THRESHOLD' is that 'mpn_mul_1' is +much faster than 'mpn_divrem_1' (often by a factor of 5, or more). + + +File: gmp.info, Node: Other Algorithms, Next: Assembly Coding, Prev: Radix Conversion Algorithms, Up: Algorithms + +15.7 Other Algorithms +===================== + +* Menu: + +* Prime Testing Algorithm:: +* Factorial Algorithm:: +* Binomial Coefficients Algorithm:: +* Fibonacci Numbers Algorithm:: +* Lucas Numbers Algorithm:: +* Random Number Algorithms:: + + +File: gmp.info, Node: Prime Testing Algorithm, Next: Factorial Algorithm, Prev: Other Algorithms, Up: Other Algorithms + +15.7.1 Prime Testing +-------------------- + +The primality testing in 'mpz_probab_prime_p' (*note Number Theoretic +Functions::) first does some trial division by small factors and then +uses the Miller-Rabin probabilistic primality testing algorithm, as +described in Knuth section 4.5.4 algorithm P (*note References::). + + For an odd input n, and with n = q*2^k+1 where q is odd, this +algorithm selects a random base x and tests whether x^q mod n is 1 or +-1, or an x^(q*2^j) mod n is 1, for 1<=j<=k. If so then n is probably +prime, if not then n is definitely composite. + + Any prime n will pass the test, but some composites do too. Such +composites are known as strong pseudoprimes to base x. No n is a strong +pseudoprime to more than 1/4 of all bases (see Knuth exercise 22), hence +with x chosen at random there's no more than a 1/4 chance a "probable +prime" will in fact be composite. + + In fact strong pseudoprimes are quite rare, making the test much more +powerful than this analysis would suggest, but 1/4 is all that's proven +for an arbitrary n. + + +File: gmp.info, Node: Factorial Algorithm, Next: Binomial Coefficients Algorithm, Prev: Prime Testing Algorithm, Up: Other Algorithms + +15.7.2 Factorial +---------------- + +Factorials are calculated by a combination of two algorithms. An idea +is shared among them: to compute the odd part of the factorial; a final +step takes account of the power of 2 term, by shifting. + + For small n, the odd factor of n! is computed with the simple +observation that it is equal to the product of all positive odd numbers +smaller than n times the odd factor of [n/2]!, where [x] is the integer +part of x, and so on recursively. The procedure can be best illustrated +with an example, + + 23! = (23.21.19.17.15.13.11.9.7.5.3)(11.9.7.5.3)(5.3)2^{19} + + Current code collects all the factors in a single list, with a loop +and no recursion, and computes the product, with no special care for +repeated chunks. + + When n is larger, computations pass through prime sieving. A helper +function is used, as suggested by Peter Luschny: + + n + ----- + n! | | L(p,n) + msf(n) = -------------- = | | p + [n/2]!^2.2^k p=3 + + Where p ranges on odd prime numbers. The exponent k is chosen to +obtain an odd integer number: k is the number of 1 bits in the binary +representation of [n/2]. The function L(p,n) can be defined as zero +when p is composite, and, for any prime p, it is computed with: + + --- + \ n + L(p,n) = / [---] mod 2 <= log (n) . + --- p^i p + i>0 + + With this helper function, we are able to compute the odd part of n! +using the recursion implied by n!=[n/2]!^2*msf(n)*2^k. The recursion +stops using the small-n algorithm on some [n/2^i]. + + Both the above algorithms use binary splitting to compute the product +of many small factors. At first as many products as possible are +accumulated in a single register, generating a list of factors that fit +in a machine word. This list is then split into halves, and the product +is computed recursively. + + Such splitting is more efficient than repeated Nx1 multiplies since +it forms big multiplies, allowing Karatsuba and higher algorithms to be +used. And even below the Karatsuba threshold a big block of work can be +more efficient for the basecase algorithm. + + +File: gmp.info, Node: Binomial Coefficients Algorithm, Next: Fibonacci Numbers Algorithm, Prev: Factorial Algorithm, Up: Other Algorithms + +15.7.3 Binomial Coefficients +---------------------------- + +Binomial coefficients C(n,k) are calculated by first arranging k <= n/2 +using C(n,k) = C(n,n-k) if necessary, and then evaluating the following +product simply from i=2 to i=k. + + k (n-k+i) + C(n,k) = (n-k+1) * prod ------- + i=2 i + + It's easy to show that each denominator i will divide the product so +far, so the exact division algorithm is used (*note Exact Division::). + + The numerators n-k+i and denominators i are first accumulated into as +many fit a limb, to save multi-precision operations, though for +'mpz_bin_ui' this applies only to the divisors, since n is an 'mpz_t' +and n-k+i in general won't fit in a limb at all. + + +File: gmp.info, Node: Fibonacci Numbers Algorithm, Next: Lucas Numbers Algorithm, Prev: Binomial Coefficients Algorithm, Up: Other Algorithms + +15.7.4 Fibonacci Numbers +------------------------ + +The Fibonacci functions 'mpz_fib_ui' and 'mpz_fib2_ui' are designed for +calculating isolated F[n] or F[n],F[n-1] values efficiently. + + For small n, a table of single limb values in '__gmp_fib_table' is +used. On a 32-bit limb this goes up to F[47], or on a 64-bit limb up to +F[93]. For convenience the table starts at F[-1]. + + Beyond the table, values are generated with a binary powering +algorithm, calculating a pair F[n] and F[n-1] working from high to low +across the bits of n. The formulas used are + + F[2k+1] = 4*F[k]^2 - F[k-1]^2 + 2*(-1)^k + F[2k-1] = F[k]^2 + F[k-1]^2 + + F[2k] = F[2k+1] - F[2k-1] + + At each step, k is the high b bits of n. If the next bit of n is 0 +then F[2k],F[2k-1] is used, or if it's a 1 then F[2k+1],F[2k] is used, +and the process repeated until all bits of n are incorporated. Notice +these formulas require just two squares per bit of n. + + It'd be possible to handle the first few n above the single limb +table with simple additions, using the defining Fibonacci recurrence +F[k+1]=F[k]+F[k-1], but this is not done since it usually turns out to +be faster for only about 10 or 20 values of n, and including a block of +code for just those doesn't seem worthwhile. If they really mattered +it'd be better to extend the data table. + + Using a table avoids lots of calculations on small numbers, and makes +small n go fast. A bigger table would make more small n go fast, it's +just a question of balancing size against desired speed. For GMP the +code is kept compact, with the emphasis primarily on a good powering +algorithm. + + 'mpz_fib2_ui' returns both F[n] and F[n-1], but 'mpz_fib_ui' is only +interested in F[n]. In this case the last step of the algorithm can +become one multiply instead of two squares. One of the following two +formulas is used, according as n is odd or even. + + F[2k] = F[k]*(F[k]+2F[k-1]) + + F[2k+1] = (2F[k]+F[k-1])*(2F[k]-F[k-1]) + 2*(-1)^k + + F[2k+1] here is the same as above, just rearranged to be a multiply. +For interest, the 2*(-1)^k term both here and above can be applied just +to the low limb of the calculation, without a carry or borrow into +further limbs, which saves some code size. See comments with +'mpz_fib_ui' and the internal 'mpn_fib2_ui' for how this is done. + + +File: gmp.info, Node: Lucas Numbers Algorithm, Next: Random Number Algorithms, Prev: Fibonacci Numbers Algorithm, Up: Other Algorithms + +15.7.5 Lucas Numbers +-------------------- + +'mpz_lucnum2_ui' derives a pair of Lucas numbers from a pair of +Fibonacci numbers with the following simple formulas. + + L[k] = F[k] + 2*F[k-1] + L[k-1] = 2*F[k] - F[k-1] + + 'mpz_lucnum_ui' is only interested in L[n], and some work can be +saved. Trailing zero bits on n can be handled with a single square +each. + + L[2k] = L[k]^2 - 2*(-1)^k + + And the lowest 1 bit can be handled with one multiply of a pair of +Fibonacci numbers, similar to what 'mpz_fib_ui' does. + + L[2k+1] = 5*F[k-1]*(2*F[k]+F[k-1]) - 4*(-1)^k + + +File: gmp.info, Node: Random Number Algorithms, Prev: Lucas Numbers Algorithm, Up: Other Algorithms + +15.7.6 Random Numbers +--------------------- + +For the 'urandomb' functions, random numbers are generated simply by +concatenating bits produced by the generator. As long as the generator +has good randomness properties this will produce well-distributed N bit +numbers. + + For the 'urandomm' functions, random numbers in a range 0<=R48 bit pieces is convenient. With some +care though six 21x32->53 bit products can be used, if one of the lower +two 21-bit pieces also uses the sign bit. + + For the 'mpn_mul_1' family of functions on a 64-bit machine, the +invariant single limb is split at the start, into 3 or 4 pieces. Inside +the loop, the bignum operand is split into 32-bit pieces. Fast +conversion of these unsigned 32-bit pieces to floating point is highly +machine-dependent. In some cases, reading the data into the integer +unit, zero-extending to 64-bits, then transferring to the floating point +unit back via memory is the only option. + + Converting partial products back to 64-bit limbs is usually best done +as a signed conversion. Since all values are smaller than 2^53, signed +and unsigned are the same, but most processors lack unsigned +conversions. + + + + Here is a diagram showing 16x32 bit products for an 'mpn_mul_1' or +'mpn_addmul_1' with a 64-bit limb. The single limb operand V is split +into four 16-bit parts. The multi-limb operand U is split in the loop +into two 32-bit parts. + + +---+---+---+---+ + |v48|v32|v16|v00| V operand + +---+---+---+---+ + + +-------+---+---+ + x | u32 | u00 | U operand (one limb) + +---------------+ + + --------------------------------- + + +-----------+ + | u00 x v00 | p00 48-bit products + +-----------+ + +-----------+ + | u00 x v16 | p16 + +-----------+ + +-----------+ + | u00 x v32 | p32 + +-----------+ + +-----------+ + | u00 x v48 | p48 + +-----------+ + +-----------+ + | u32 x v00 | r32 + +-----------+ + +-----------+ + | u32 x v16 | r48 + +-----------+ + +-----------+ + | u32 x v32 | r64 + +-----------+ + +-----------+ + | u32 x v48 | r80 + +-----------+ + + p32 and r32 can be summed using floating-point addition, and likewise +p48 and r48. p00 and p16 can be summed with r64 and r80 from the +previous iteration. + + For each loop then, four 49-bit quantities are transferred to the +integer unit, aligned as follows, + + |-----64bits----|-----64bits----| + +------------+ + | p00 + r64' | i00 + +------------+ + +------------+ + | p16 + r80' | i16 + +------------+ + +------------+ + | p32 + r32 | i32 + +------------+ + +------------+ + | p48 + r48 | i48 + +------------+ + + The challenge then is to sum these efficiently and add in a carry +limb, generating a low 64-bit result limb and a high 33-bit carry limb +(i48 extends 33 bits into the high half). + + +File: gmp.info, Node: Assembly SIMD Instructions, Next: Assembly Software Pipelining, Prev: Assembly Floating Point, Up: Assembly Coding + +15.8.7 SIMD Instructions +------------------------ + +The single-instruction multiple-data support in current microprocessors +is aimed at signal processing algorithms where each data point can be +treated more or less independently. There's generally not much support +for propagating the sort of carries that arise in GMP. + + SIMD multiplications of say four 16x16 bit multiplies only do as much +work as one 32x32 from GMP's point of view, and need some shifts and +adds besides. But of course if say the SIMD form is fully pipelined and +uses less instruction decoding then it may still be worthwhile. + + On the x86 chips, MMX has so far found a use in 'mpn_rshift' and +'mpn_lshift', and is used in a special case for 16-bit multipliers in +the P55 'mpn_mul_1'. SSE2 is used for Pentium 4 'mpn_mul_1', +'mpn_addmul_1', and 'mpn_submul_1'. + + +File: gmp.info, Node: Assembly Software Pipelining, Next: Assembly Loop Unrolling, Prev: Assembly SIMD Instructions, Up: Assembly Coding + +15.8.8 Software Pipelining +-------------------------- + +Software pipelining consists of scheduling instructions around the +branch point in a loop. For example a loop might issue a load not for +use in the present iteration but the next, thereby allowing extra cycles +for the data to arrive from memory. + + Naturally this is wanted only when doing things like loads or +multiplies that take several cycles to complete, and only where a CPU +has multiple functional units so that other work can be done in the +meantime. + + A pipeline with several stages will have a data value in progress at +each stage and each loop iteration moves them along one stage. This is +like juggling. + + If the latency of some instruction is greater than the loop time then +it will be necessary to unroll, so one register has a result ready to +use while another (or multiple others) are still in progress (*note +Assembly Loop Unrolling::). + + +File: gmp.info, Node: Assembly Loop Unrolling, Next: Assembly Writing Guide, Prev: Assembly Software Pipelining, Up: Assembly Coding + +15.8.9 Loop Unrolling +--------------------- + +Loop unrolling consists of replicating code so that several limbs are +processed in each loop. At a minimum this reduces loop overheads by a +corresponding factor, but it can also allow better register usage, for +example alternately using one register combination and then another. +Judicious use of 'm4' macros can help avoid lots of duplication in the +source code. + + Any amount of unrolling can be handled with a loop counter that's +decremented by N each time, stopping when the remaining count is less +than the further N the loop will process. Or by subtracting N at the +start, the termination condition becomes when the counter C is less than +0 (and the count of remaining limbs is C+N). + + Alternately for a power of 2 unroll the loop count and remainder can +be established with a shift and mask. This is convenient if also making +a computed jump into the middle of a large loop. + + The limbs not a multiple of the unrolling can be handled in various +ways, for example + + * A simple loop at the end (or the start) to process the excess. + Care will be wanted that it isn't too much slower than the unrolled + part. + + * A set of binary tests, for example after an 8-limb unrolling, test + for 4 more limbs to process, then a further 2 more or not, and + finally 1 more or not. This will probably take more code space + than a simple loop. + + * A 'switch' statement, providing separate code for each possible + excess, for example an 8-limb unrolling would have separate code + for 0 remaining, 1 remaining, etc, up to 7 remaining. This might + take a lot of code, but may be the best way to optimize all cases + in combination with a deep pipelined loop. + + * A computed jump into the middle of the loop, thus making the first + iteration handle the excess. This should make times smoothly + increase with size, which is attractive, but setups for the jump + and adjustments for pointers can be tricky and could become quite + difficult in combination with deep pipelining. + + +File: gmp.info, Node: Assembly Writing Guide, Prev: Assembly Loop Unrolling, Up: Assembly Coding + +15.8.10 Writing Guide +--------------------- + +This is a guide to writing software pipelined loops for processing limb +vectors in assembly. + + First determine the algorithm and which instructions are needed. +Code it without unrolling or scheduling, to make sure it works. On a +3-operand CPU try to write each new value to a new register, this will +greatly simplify later steps. + + Then note for each instruction the functional unit and/or issue port +requirements. If an instruction can use either of two units, like U0 or +U1 then make a category "U0/U1". Count the total using each unit (or +combined unit), and count all instructions. + + Figure out from those counts the best possible loop time. The goal +will be to find a perfect schedule where instruction latencies are +completely hidden. The total instruction count might be the limiting +factor, or perhaps a particular functional unit. It might be possible +to tweak the instructions to help the limiting factor. + + Suppose the loop time is N, then make N issue buckets, with the final +loop branch at the end of the last. Now fill the buckets with dummy +instructions using the functional units desired. Run this to make sure +the intended speed is reached. + + Now replace the dummy instructions with the real instructions from +the slow but correct loop you started with. The first will typically be +a load instruction. Then the instruction using that value is placed in +a bucket an appropriate distance down. Run the loop again, to check it +still runs at target speed. + + Keep placing instructions, frequently measuring the loop. After a +few you will need to wrap around from the last bucket back to the top of +the loop. If you used the new-register for new-value strategy above +then there will be no register conflicts. If not then take care not to +clobber something already in use. Changing registers at this time is +very error prone. + + The loop will overlap two or more of the original loop iterations, +and the computation of one vector element result will be started in one +iteration of the new loop, and completed one or several iterations +later. + + The final step is to create feed-in and wind-down code for the loop. +A good way to do this is to make a copy (or copies) of the loop at the +start and delete those instructions which don't have valid antecedents, +and at the end replicate and delete those whose results are unwanted +(including any further loads). + + The loop will have a minimum number of limbs loaded and processed, so +the feed-in code must test if the request size is smaller and skip +either to a suitable part of the wind-down or to special code for small +sizes. + + +File: gmp.info, Node: Internals, Next: Contributors, Prev: Algorithms, Up: Top + +16 Internals +************ + +*This chapter is provided only for informational purposes and the +various internals described here may change in future GMP releases. +Applications expecting to be compatible with future releases should use +only the documented interfaces described in previous chapters.* + +* Menu: + +* Integer Internals:: +* Rational Internals:: +* Float Internals:: +* Raw Output Internals:: +* C++ Interface Internals:: + + +File: gmp.info, Node: Integer Internals, Next: Rational Internals, Prev: Internals, Up: Internals + +16.1 Integer Internals +====================== + +'mpz_t' variables represent integers using sign and magnitude, in space +dynamically allocated and reallocated. The fields are as follows. + +'_mp_size' + The number of limbs, or the negative of that when representing a + negative integer. Zero is represented by '_mp_size' set to zero, + in which case the '_mp_d' data is undefined. + +'_mp_d' + A pointer to an array of limbs which is the magnitude. These are + stored "little endian" as per the 'mpn' functions, so '_mp_d[0]' is + the least significant limb and '_mp_d[ABS(_mp_size)-1]' is the most + significant. Whenever '_mp_size' is non-zero, the most significant + limb is non-zero. + + Currently there's always at least one readable limb, so for + instance 'mpz_get_ui' can fetch '_mp_d[0]' unconditionally (though + its value is undefined if '_mp_size' is zero). + +'_mp_alloc' + '_mp_alloc' is the number of limbs currently allocated at '_mp_d', + and normally '_mp_alloc >= ABS(_mp_size)'. When an 'mpz' routine + is about to (or might be about to) increase '_mp_size', it checks + '_mp_alloc' to see whether there's enough space, and reallocates if + not. 'MPZ_REALLOC' is generally used for this. + + 'mpz_t' variables initialised with the 'mpz_roinit_n' function or + the 'MPZ_ROINIT_N' macro have '_mp_alloc = 0' but can have a + non-zero '_mp_size'. They can only be used as read-only constants. + See *note Integer Special Functions:: for details. + + The various bitwise logical functions like 'mpz_and' behave as if +negative values were two's complement. But sign and magnitude is always +used internally, and necessary adjustments are made during the +calculations. Sometimes this isn't pretty, but sign and magnitude are +best for other routines. + + Some internal temporary variables are set up with 'MPZ_TMP_INIT' and +these have '_mp_d' space obtained from 'TMP_ALLOC' rather than the +memory allocation functions. Care is taken to ensure that these are big +enough that no reallocation is necessary (since it would have +unpredictable consequences). + + '_mp_size' and '_mp_alloc' are 'int', although 'mp_size_t' is usually +a 'long'. This is done to make the fields just 32 bits on some 64 bits +systems, thereby saving a few bytes of data space but still providing +plenty of range. + + +File: gmp.info, Node: Rational Internals, Next: Float Internals, Prev: Integer Internals, Up: Internals + +16.2 Rational Internals +======================= + +'mpq_t' variables represent rationals using an 'mpz_t' numerator and +denominator (*note Integer Internals::). + + The canonical form adopted is denominator positive (and non-zero), no +common factors between numerator and denominator, and zero uniquely +represented as 0/1. + + It's believed that casting out common factors at each stage of a +calculation is best in general. A GCD is an O(N^2) operation so it's +better to do a few small ones immediately than to delay and have to do a +big one later. Knowing the numerator and denominator have no common +factors can be used for example in 'mpq_mul' to make only two cross GCDs +necessary, not four. + + This general approach to common factors is badly sub-optimal in the +presence of simple factorizations or little prospect for cancellation, +but GMP has no way to know when this will occur. As per *note +Efficiency::, that's left to applications. The 'mpq_t' framework might +still suit, with 'mpq_numref' and 'mpq_denref' for direct access to the +numerator and denominator, or of course 'mpz_t' variables can be used +directly. + + +File: gmp.info, Node: Float Internals, Next: Raw Output Internals, Prev: Rational Internals, Up: Internals + +16.3 Float Internals +==================== + +Efficient calculation is the primary aim of GMP floats and the use of +whole limbs and simple rounding facilitates this. + + 'mpf_t' floats have a variable precision mantissa and a single +machine word signed exponent. The mantissa is represented using sign +and magnitude. + + most least + significant significant + limb limb + + _mp_d + |---- _mp_exp ---> | + _____ _____ _____ _____ _____ + |_____|_____|_____|_____|_____| + . <------------ radix point + + <-------- _mp_size ---------> + + +The fields are as follows. + +'_mp_size' + The number of limbs currently in use, or the negative of that when + representing a negative value. Zero is represented by '_mp_size' + and '_mp_exp' both set to zero, and in that case the '_mp_d' data + is unused. (In the future '_mp_exp' might be undefined when + representing zero.) + +'_mp_prec' + The precision of the mantissa, in limbs. In any calculation the + aim is to produce '_mp_prec' limbs of result (the most significant + being non-zero). + +'_mp_d' + A pointer to the array of limbs which is the absolute value of the + mantissa. These are stored "little endian" as per the 'mpn' + functions, so '_mp_d[0]' is the least significant limb and + '_mp_d[ABS(_mp_size)-1]' the most significant. + + The most significant limb is always non-zero, but there are no + other restrictions on its value, in particular the highest 1 bit + can be anywhere within the limb. + + '_mp_prec+1' limbs are allocated to '_mp_d', the extra limb being + for convenience (see below). There are no reallocations during a + calculation, only in a change of precision with 'mpf_set_prec'. + +'_mp_exp' + The exponent, in limbs, determining the location of the implied + radix point. Zero means the radix point is just above the most + significant limb. Positive values mean a radix point offset + towards the lower limbs and hence a value >= 1, as for example in + the diagram above. Negative exponents mean a radix point further + above the highest limb. + + Naturally the exponent can be any value, it doesn't have to fall + within the limbs as the diagram shows, it can be a long way above + or a long way below. Limbs other than those included in the + '{_mp_d,_mp_size}' data are treated as zero. + + The '_mp_size' and '_mp_prec' fields are 'int', although the +'mp_size_t' type is usually a 'long'. The '_mp_exp' field is usually +'long'. This is done to make some fields just 32 bits on some 64 bits +systems, thereby saving a few bytes of data space but still providing +plenty of precision and a very large range. + + +The following various points should be noted. + +Low Zeros + The least significant limbs '_mp_d[0]' etc can be zero, though such + low zeros can always be ignored. Routines likely to produce low + zeros check and avoid them to save time in subsequent calculations, + but for most routines they're quite unlikely and aren't checked. + +Mantissa Size Range + The '_mp_size' count of limbs in use can be less than '_mp_prec' if + the value can be represented in less. This means low precision + values or small integers stored in a high precision 'mpf_t' can + still be operated on efficiently. + + '_mp_size' can also be greater than '_mp_prec'. Firstly a value is + allowed to use all of the '_mp_prec+1' limbs available at '_mp_d', + and secondly when 'mpf_set_prec_raw' lowers '_mp_prec' it leaves + '_mp_size' unchanged and so the size can be arbitrarily bigger than + '_mp_prec'. + +Rounding + All rounding is done on limb boundaries. Calculating '_mp_prec' + limbs with the high non-zero will ensure the application requested + minimum precision is obtained. + + The use of simple "trunc" rounding towards zero is efficient, since + there's no need to examine extra limbs and increment or decrement. + +Bit Shifts + Since the exponent is in limbs, there are no bit shifts in basic + operations like 'mpf_add' and 'mpf_mul'. When differing exponents + are encountered all that's needed is to adjust pointers to line up + the relevant limbs. + + Of course 'mpf_mul_2exp' and 'mpf_div_2exp' will require bit + shifts, but the choice is between an exponent in limbs which + requires shifts there, or one in bits which requires them almost + everywhere else. + +Use of '_mp_prec+1' Limbs + The extra limb on '_mp_d' ('_mp_prec+1' rather than just + '_mp_prec') helps when an 'mpf' routine might get a carry from its + operation. 'mpf_add' for instance will do an 'mpn_add' of + '_mp_prec' limbs. If there's no carry then that's the result, but + if there is a carry then it's stored in the extra limb of space and + '_mp_size' becomes '_mp_prec+1'. + + Whenever '_mp_prec+1' limbs are held in a variable, the low limb is + not needed for the intended precision, only the '_mp_prec' high + limbs. But zeroing it out or moving the rest down is unnecessary. + Subsequent routines reading the value will simply take the high + limbs they need, and this will be '_mp_prec' if their target has + that same precision. This is no more than a pointer adjustment, + and must be checked anyway since the destination precision can be + different from the sources. + + Copy functions like 'mpf_set' will retain a full '_mp_prec+1' limbs + if available. This ensures that a variable which has '_mp_size' + equal to '_mp_prec+1' will get its full exact value copied. + Strictly speaking this is unnecessary since only '_mp_prec' limbs + are needed for the application's requested precision, but it's + considered that an 'mpf_set' from one variable into another of the + same precision ought to produce an exact copy. + +Application Precisions + '__GMPF_BITS_TO_PREC' converts an application requested precision + to an '_mp_prec'. The value in bits is rounded up to a whole limb + then an extra limb is added since the most significant limb of + '_mp_d' is only non-zero and therefore might contain only one bit. + + '__GMPF_PREC_TO_BITS' does the reverse conversion, and removes the + extra limb from '_mp_prec' before converting to bits. The net + effect of reading back with 'mpf_get_prec' is simply the precision + rounded up to a multiple of 'mp_bits_per_limb'. + + Note that the extra limb added here for the high only being + non-zero is in addition to the extra limb allocated to '_mp_d'. + For example with a 32-bit limb, an application request for 250 bits + will be rounded up to 8 limbs, then an extra added for the high + being only non-zero, giving an '_mp_prec' of 9. '_mp_d' then gets + 10 limbs allocated. Reading back with 'mpf_get_prec' will take + '_mp_prec' subtract 1 limb and multiply by 32, giving 256 bits. + + Strictly speaking, the fact that the high limb has at least one bit + means that a float with, say, 3 limbs of 32-bits each will be + holding at least 65 bits, but for the purposes of 'mpf_t' it's + considered simply to be 64 bits, a nice multiple of the limb size. + + +File: gmp.info, Node: Raw Output Internals, Next: C++ Interface Internals, Prev: Float Internals, Up: Internals + +16.4 Raw Output Internals +========================= + +'mpz_out_raw' uses the following format. + + +------+------------------------+ + | size | data bytes | + +------+------------------------+ + + The size is 4 bytes written most significant byte first, being the +number of subsequent data bytes, or the two's complement negative of +that when a negative integer is represented. The data bytes are the +absolute value of the integer, written most significant byte first. + + The most significant data byte is always non-zero, so the output is +the same on all systems, irrespective of limb size. + + In GMP 1, leading zero bytes were written to pad the data bytes to a +multiple of the limb size. 'mpz_inp_raw' will still accept this, for +compatibility. + + The use of "big endian" for both the size and data fields is +deliberate, it makes the data easy to read in a hex dump of a file. +Unfortunately it also means that the limb data must be reversed when +reading or writing, so neither a big endian nor little endian system can +just read and write '_mp_d'. + + +File: gmp.info, Node: C++ Interface Internals, Prev: Raw Output Internals, Up: Internals + +16.5 C++ Interface Internals +============================ + +A system of expression templates is used to ensure something like +'a=b+c' turns into a simple call to 'mpz_add' etc. For 'mpf_class' the +scheme also ensures the precision of the final destination is used for +any temporaries within a statement like 'f=w*x+y*z'. These are +important features which a naive implementation cannot provide. + + A simplified description of the scheme follows. The true scheme is +complicated by the fact that expressions have different return types. +For detailed information, refer to the source code. + + To perform an operation, say, addition, we first define a "function +object" evaluating it, + + struct __gmp_binary_plus + { + static void eval(mpf_t f, const mpf_t g, const mpf_t h) + { + mpf_add(f, g, h); + } + }; + +And an "additive expression" object, + + __gmp_expr<__gmp_binary_expr > + operator+(const mpf_class &f, const mpf_class &g) + { + return __gmp_expr + <__gmp_binary_expr >(f, g); + } + + The seemingly redundant '__gmp_expr<__gmp_binary_expr<...>>' is used +to encapsulate any possible kind of expression into a single template +type. In fact even 'mpf_class' etc are 'typedef' specializations of +'__gmp_expr'. + + Next we define assignment of '__gmp_expr' to 'mpf_class'. + + template + mpf_class & mpf_class::operator=(const __gmp_expr &expr) + { + expr.eval(this->get_mpf_t(), this->precision()); + return *this; + } + + template + void __gmp_expr<__gmp_binary_expr >::eval + (mpf_t f, mp_bitcnt_t precision) + { + Op::eval(f, expr.val1.get_mpf_t(), expr.val2.get_mpf_t()); + } + + where 'expr.val1' and 'expr.val2' are references to the expression's +operands (here 'expr' is the '__gmp_binary_expr' stored within the +'__gmp_expr'). + + This way, the expression is actually evaluated only at the time of +assignment, when the required precision (that of 'f') is known. +Furthermore the target 'mpf_t' is now available, thus we can call +'mpf_add' directly with 'f' as the output argument. + + Compound expressions are handled by defining operators taking +subexpressions as their arguments, like this: + + template + __gmp_expr + <__gmp_binary_expr<__gmp_expr, __gmp_expr, __gmp_binary_plus> > + operator+(const __gmp_expr &expr1, const __gmp_expr &expr2) + { + return __gmp_expr + <__gmp_binary_expr<__gmp_expr, __gmp_expr, __gmp_binary_plus> > + (expr1, expr2); + } + + And the corresponding specializations of '__gmp_expr::eval': + + template + void __gmp_expr + <__gmp_binary_expr<__gmp_expr, __gmp_expr, Op> >::eval + (mpf_t f, mp_bitcnt_t precision) + { + // declare two temporaries + mpf_class temp1(expr.val1, precision), temp2(expr.val2, precision); + Op::eval(f, temp1.get_mpf_t(), temp2.get_mpf_t()); + } + + The expression is thus recursively evaluated to any level of +complexity and all subexpressions are evaluated to the precision of 'f'. + + +File: gmp.info, Node: Contributors, Next: References, Prev: Internals, Up: Top + +Appendix A Contributors +*********************** + +Torbjörn Granlund wrote the original GMP library and is still the main +developer. Code not explicitly attributed to others was contributed by +Torbjörn. Several other individuals and organizations have contributed +GMP. Here is a list in chronological order on first contribution: + + Gunnar Sjödin and Hans Riesel helped with mathematical problems in +early versions of the library. + + Richard Stallman helped with the interface design and revised the +first version of this manual. + + Brian Beuning and Doug Lea helped with testing of early versions of +the library and made creative suggestions. + + John Amanatides of York University in Canada contributed the function +'mpz_probab_prime_p'. + + Paul Zimmermann wrote the REDC-based mpz_powm code, the +Schönhage-Strassen FFT multiply code, and the Karatsuba square root +code. He also improved the Toom3 code for GMP 4.2. Paul sparked the +development of GMP 2, with his comparisons between bignum packages. The +ECMNET project Paul is organizing was a driving force behind many of the +optimizations in GMP 3. Paul also wrote the new GMP 4.3 nth root code +(with Torbjörn). + + Ken Weber (Kent State University, Universidade Federal do Rio Grande +do Sul) contributed now defunct versions of 'mpz_gcd', 'mpz_divexact', +'mpn_gcd', and 'mpn_bdivmod', partially supported by CNPq (Brazil) grant +301314194-2. + + Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' +configure. He has also made valuable suggestions and tested numerous +intermediary releases. + + Joachim Hollman was involved in the design of the 'mpf' interface, +and in the 'mpz' design revisions for version 2. + + Bennet Yee contributed the initial versions of 'mpz_jacobi' and +'mpz_legendre'. + + Andreas Schwab contributed the files 'mpn/m68k/lshift.S' and +'mpn/m68k/rshift.S' (now in '.asm' form). + + Robert Harley of Inria, France and David Seal of ARM, England, +suggested clever improvements for population count. Robert also wrote +highly optimized Karatsuba and 3-way Toom multiplication functions for +GMP 3, and contributed the ARM assembly code. + + Torsten Ekedahl of the Mathematical Department of Stockholm +University provided significant inspiration during several phases of the +GMP development. His mathematical expertise helped improve several +algorithms. + + Linus Nordberg wrote the new configure system based on autoconf and +implemented the new random functions. + + Kevin Ryde worked on a large number of things: optimized x86 code, m4 +asm macros, parameter tuning, speed measuring, the configure system, +function inlining, divisibility tests, bit scanning, Jacobi symbols, +Fibonacci and Lucas number functions, printf and scanf functions, perl +interface, demo expression parser, the algorithms chapter in the manual, +'gmpasm-mode.el', and various miscellaneous improvements elsewhere. + + Kent Boortz made the Mac OS 9 port. + + Steve Root helped write the optimized alpha 21264 assembly code. + + Gerardo Ballabio wrote the 'gmpxx.h' C++ class interface and the C++ +'istream' input routines. + + Jason Moxham rewrote 'mpz_fac_ui'. + + Pedro Gimeno implemented the Mersenne Twister and made other random +number improvements. + + Niels Möller wrote the sub-quadratic GCD, extended GCD and Jacobi +code, the quadratic Hensel division code, and (with Torbjörn) the new +divide and conquer division code for GMP 4.3. Niels also helped +implement the new Toom multiply code for GMP 4.3 and implemented helper +functions to simplify Toom evaluations for GMP 5.0. He wrote the +original version of mpn_mulmod_bnm1, and he is the main author of the +mini-gmp package used for gmp bootstrapping. + + Alberto Zanoni and Marco Bodrato suggested the unbalanced multiply +strategy, and found the optimal strategies for evaluation and +interpolation in Toom multiplication. + + Marco Bodrato helped implement the new Toom multiply code for GMP 4.3 +and implemented most of the new Toom multiply and squaring code for 5.0. +He is the main author of the current mpn_mulmod_bnm1, mpn_mullo_n, and +mpn_sqrlo. Marco also wrote the functions mpn_invert and +mpn_invertappr, and improved the speed of integer root extraction. He +is the author of mini-mpq, an additional layer to mini-gmp; of most of +the combinatorial functions and the BPSW primality testing +implementation, for both the main library and the mini-gmp package. + + David Harvey suggested the internal function 'mpn_bdiv_dbm1', +implementing division relevant to Toom multiplication. He also worked +on fast assembly sequences, in particular on a fast AMD64 +'mpn_mul_basecase'. He wrote the internal middle product functions +'mpn_mulmid_basecase', 'mpn_toom42_mulmid', 'mpn_mulmid_n' and related +helper routines. + + Martin Boij wrote 'mpn_perfect_power_p'. + + Marc Glisse improved 'gmpxx.h': use fewer temporaries (faster), +specializations of 'numeric_limits' and 'common_type', C++11 features +(move constructors, explicit bool conversion, UDL), make the conversion +from 'mpq_class' to 'mpz_class' explicit, optimize operations where one +argument is a small compile-time constant, replace some heap allocations +by stack allocations. He also fixed the eofbit handling of C++ streams, +and removed one division from 'mpq/aors.c'. + + David S Miller wrote assembly code for SPARC T3 and T4. + + Mark Sofroniou cleaned up the types of mul_fft.c, letting it work for +huge operands. + + Ulrich Weigand ported GMP to the powerpc64le ABI. + + (This list is chronological, not ordered after significance. If you +have contributed to GMP but are not listed above, please tell + about the omission!) + + The development of floating point functions of GNU MP 2 was supported +in part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO +(POlynomial System SOlving). + + The development of GMP 2, 3, and 4.0 was supported in part by the IDA +Center for Computing Sciences. + + The development of GMP 4.3, 5.0, and 5.1 was supported in part by the +Swedish Foundation for Strategic Research. + + Thanks go to Hans Thorsen for donating an SGI system for the GMP test +system environment. + + +File: gmp.info, Node: References, Next: GNU Free Documentation License, Prev: Contributors, Up: Top + +Appendix B References +********************* + +B.1 Books +========= + + * Jonathan M. Borwein and Peter B. Borwein, "Pi and the AGM: A Study + in Analytic Number Theory and Computational Complexity", Wiley, + 1998. + + * Richard Crandall and Carl Pomerance, "Prime Numbers: A + Computational Perspective", 2nd edition, Springer-Verlag, 2005. + + + * Henri Cohen, "A Course in Computational Algebraic Number Theory", + Graduate Texts in Mathematics number 138, Springer-Verlag, 1993. + + + * Donald E. Knuth, "The Art of Computer Programming", volume 2, + "Seminumerical Algorithms", 3rd edition, Addison-Wesley, 1998. + + + * John D. Lipson, "Elements of Algebra and Algebraic Computing", The + Benjamin Cummings Publishing Company Inc, 1981. + + * Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, + "Handbook of Applied Cryptography", + + + * Richard M. Stallman and the GCC Developer Community, "Using the GNU + Compiler Collection", Free Software Foundation, 2008, available + online , and in the GCC package + + +B.2 Papers +========== + + * Yves Bertot, Nicolas Magaud and Paul Zimmermann, "A Proof of GMP + Square Root", Journal of Automated Reasoning, volume 29, 2002, pp. + 225-252. Also available online as INRIA Research Report 4475, June + 2002, + + * Christoph Burnikel and Joachim Ziegler, "Fast Recursive Division", + Max-Planck-Institut fuer Informatik Research Report MPI-I-98-1-022, + + + * Torbjörn Granlund and Peter L. Montgomery, "Division by Invariant + Integers using Multiplication", in Proceedings of the SIGPLAN + PLDI'94 Conference, June 1994. Also available + . + + * Niels Möller and Torbjörn Granlund, "Improved division by invariant + integers", IEEE Transactions on Computers, 11 June 2010. + + + * Torbjörn Granlund and Niels Möller, "Division of integers large and + small", to appear. + + * Tudor Jebelean, "An algorithm for exact division", Journal of + Symbolic Computation, volume 15, 1993, pp. 169-180. Research + report version available + + + * Tudor Jebelean, "Exact Division with Karatsuba Complexity - + Extended Abstract", RISC-Linz technical report 96-31, + + + * Tudor Jebelean, "Practical Integer Division with Karatsuba + Complexity", ISSAC 97, pp. 339-341. Technical report available + + + * Tudor Jebelean, "A Generalization of the Binary GCD Algorithm", + ISSAC 93, pp. 111-116. Technical report version available + + + * Tudor Jebelean, "A Double-Digit Lehmer-Euclid Algorithm for Finding + the GCD of Long Integers", Journal of Symbolic Computation, volume + 19, 1995, pp. 145-157. Technical report version also available + + + * Werner Krandick and Tudor Jebelean, "Bidirectional Exact Integer + Division", Journal of Symbolic Computation, volume 21, 1996, pp. + 441-455. Early technical report version also available + + + * Makoto Matsumoto and Takuji Nishimura, "Mersenne Twister: A + 623-dimensionally equidistributed uniform pseudorandom number + generator", ACM Transactions on Modelling and Computer Simulation, + volume 8, January 1998, pp. 3-30. Available online + + + * R. Moenck and A. Borodin, "Fast Modular Transforms via Division", + Proceedings of the 13th Annual IEEE Symposium on Switching and + Automata Theory, October 1972, pp. 90-96. Reprinted as "Fast + Modular Transforms", Journal of Computer and System Sciences, + volume 8, number 3, June 1974, pp. 366-386. + + * Niels Möller, "On Schönhage's algorithm and subquadratic integer + GCD computation", in Mathematics of Computation, volume 77, January + 2008, pp. 589-607, + + + * Peter L. Montgomery, "Modular Multiplication Without Trial + Division", in Mathematics of Computation, volume 44, number 170, + April 1985. + + * Arnold Schönhage and Volker Strassen, "Schnelle Multiplikation + grosser Zahlen", Computing 7, 1971, pp. 281-292. + + * Kenneth Weber, "The accelerated integer GCD algorithm", ACM + Transactions on Mathematical Software, volume 21, number 1, March + 1995, pp. 111-122. + + * Paul Zimmermann, "Karatsuba Square Root", INRIA Research Report + 3805, November 1999, + + + * Paul Zimmermann, "A Proof of GMP Fast Division and Square Root + Implementations", + + + * Dan Zuras, "On Squaring and Multiplying Large Integers", ARITH-11: + IEEE Symposium on Computer Arithmetic, 1993, pp. 260 to 271. + Reprinted as "More on Multiplying and Squaring Large Integers", + IEEE Transactions on Computers, volume 43, number 8, August 1994, + pp. 899-908. + + * Niels Möller, "Efficient computation of the Jacobi symbol", + + + +File: gmp.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: References, Up: Top + +Appendix C GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright © 2000-2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: gmp.info, Node: Concept Index, Next: Function Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* #include: Headers and Libraries. + (line 6) +* --build: Build Options. (line 51) +* --disable-fft: Build Options. (line 307) +* --disable-shared: Build Options. (line 44) +* --disable-static: Build Options. (line 44) +* --enable-alloca: Build Options. (line 273) +* --enable-assert: Build Options. (line 313) +* --enable-cxx: Build Options. (line 225) +* --enable-fat: Build Options. (line 160) +* --enable-profiling: Build Options. (line 317) +* --enable-profiling <1>: Profiling. (line 6) +* --exec-prefix: Build Options. (line 32) +* --host: Build Options. (line 65) +* --prefix: Build Options. (line 32) +* -finstrument-functions: Profiling. (line 66) +* 2exp functions: Efficiency. (line 43) +* 68000: Notes for Particular Systems. + (line 94) +* 80x86: Notes for Particular Systems. + (line 150) +* ABI: Build Options. (line 167) +* ABI <1>: ABI and ISA. (line 6) +* About this manual: Introduction to GMP. (line 57) +* AC_CHECK_LIB: Autoconf. (line 11) +* AIX: ABI and ISA. (line 174) +* AIX <1>: Notes for Particular Systems. + (line 7) +* Algorithms: Algorithms. (line 6) +* alloca: Build Options. (line 273) +* Allocation of memory: Custom Allocation. (line 6) +* AMD64: ABI and ISA. (line 44) +* Anonymous FTP of latest version: Introduction to GMP. (line 37) +* Application Binary Interface: ABI and ISA. (line 6) +* Arithmetic functions: Integer Arithmetic. (line 6) +* Arithmetic functions <1>: Rational Arithmetic. (line 6) +* Arithmetic functions <2>: Float Arithmetic. (line 6) +* ARM: Notes for Particular Systems. + (line 20) +* Assembly cache handling: Assembly Cache Handling. + (line 6) +* Assembly carry propagation: Assembly Carry Propagation. + (line 6) +* Assembly code organisation: Assembly Code Organisation. + (line 6) +* Assembly coding: Assembly Coding. (line 6) +* Assembly floating point: Assembly Floating Point. + (line 6) +* Assembly loop unrolling: Assembly Loop Unrolling. + (line 6) +* Assembly SIMD: Assembly SIMD Instructions. + (line 6) +* Assembly software pipelining: Assembly Software Pipelining. + (line 6) +* Assembly writing guide: Assembly Writing Guide. + (line 6) +* Assertion checking: Build Options. (line 313) +* Assertion checking <1>: Debugging. (line 74) +* Assignment functions: Assigning Integers. (line 6) +* Assignment functions <1>: Simultaneous Integer Init & Assign. + (line 6) +* Assignment functions <2>: Initializing Rationals. + (line 6) +* Assignment functions <3>: Assigning Floats. (line 6) +* Assignment functions <4>: Simultaneous Float Init & Assign. + (line 6) +* Autoconf: Autoconf. (line 6) +* Basics: GMP Basics. (line 6) +* Binomial coefficient algorithm: Binomial Coefficients Algorithm. + (line 6) +* Binomial coefficient functions: Number Theoretic Functions. + (line 137) +* Binutils strip: Known Build Problems. + (line 28) +* Bit manipulation functions: Integer Logic and Bit Fiddling. + (line 6) +* Bit scanning functions: Integer Logic and Bit Fiddling. + (line 39) +* Bit shift left: Integer Arithmetic. (line 38) +* Bit shift right: Integer Division. (line 74) +* Bits per limb: Useful Macros and Constants. + (line 7) +* Bug reporting: Reporting Bugs. (line 6) +* Build directory: Build Options. (line 19) +* Build notes for binary packaging: Notes for Package Builds. + (line 6) +* Build notes for particular systems: Notes for Particular Systems. + (line 6) +* Build options: Build Options. (line 6) +* Build problems known: Known Build Problems. + (line 6) +* Build system: Build Options. (line 51) +* Building GMP: Installing GMP. (line 6) +* Bus error: Debugging. (line 7) +* C compiler: Build Options. (line 178) +* C++ compiler: Build Options. (line 249) +* C++ interface: C++ Class Interface. (line 6) +* C++ interface internals: C++ Interface Internals. + (line 6) +* C++ istream input: C++ Formatted Input. (line 6) +* C++ ostream output: C++ Formatted Output. + (line 6) +* C++ support: Build Options. (line 225) +* CC: Build Options. (line 178) +* CC_FOR_BUILD: Build Options. (line 212) +* CFLAGS: Build Options. (line 178) +* Checker: Debugging. (line 110) +* checkergcc: Debugging. (line 117) +* Code organisation: Assembly Code Organisation. + (line 6) +* Compaq C++: Notes for Particular Systems. + (line 25) +* Comparison functions: Integer Comparisons. (line 6) +* Comparison functions <1>: Comparing Rationals. (line 6) +* Comparison functions <2>: Float Comparison. (line 6) +* Compatibility with older versions: Compatibility with older versions. + (line 6) +* Conditions for copying GNU MP: Copying. (line 6) +* Configuring GMP: Installing GMP. (line 6) +* Congruence algorithm: Exact Remainder. (line 30) +* Congruence functions: Integer Division. (line 150) +* Constants: Useful Macros and Constants. + (line 6) +* Contributors: Contributors. (line 6) +* Conventions for parameters: Parameter Conventions. + (line 6) +* Conventions for variables: Variable Conventions. + (line 6) +* Conversion functions: Converting Integers. (line 6) +* Conversion functions <1>: Rational Conversions. + (line 6) +* Conversion functions <2>: Converting Floats. (line 6) +* Copying conditions: Copying. (line 6) +* CPPFLAGS: Build Options. (line 204) +* CPU types: Introduction to GMP. (line 24) +* CPU types <1>: Build Options. (line 107) +* Cross compiling: Build Options. (line 65) +* Cryptography functions, low-level: Low-level Functions. (line 507) +* Custom allocation: Custom Allocation. (line 6) +* CXX: Build Options. (line 249) +* CXXFLAGS: Build Options. (line 249) +* Cygwin: Notes for Particular Systems. + (line 57) +* Darwin: Known Build Problems. + (line 51) +* Debugging: Debugging. (line 6) +* Demonstration programs: Demonstration Programs. + (line 6) +* Digits in an integer: Miscellaneous Integer Functions. + (line 23) +* Divisibility algorithm: Exact Remainder. (line 30) +* Divisibility functions: Integer Division. (line 136) +* Divisibility functions <1>: Integer Division. (line 150) +* Divisibility testing: Efficiency. (line 91) +* Division algorithms: Division Algorithms. (line 6) +* Division functions: Integer Division. (line 6) +* Division functions <1>: Rational Arithmetic. (line 24) +* Division functions <2>: Float Arithmetic. (line 33) +* DJGPP: Notes for Particular Systems. + (line 57) +* DJGPP <1>: Known Build Problems. + (line 18) +* DLLs: Notes for Particular Systems. + (line 70) +* DocBook: Build Options. (line 340) +* Documentation formats: Build Options. (line 333) +* Documentation license: GNU Free Documentation License. + (line 6) +* DVI: Build Options. (line 336) +* Efficiency: Efficiency. (line 6) +* Emacs: Emacs. (line 6) +* Exact division functions: Integer Division. (line 125) +* Exact remainder: Exact Remainder. (line 6) +* Example programs: Demonstration Programs. + (line 6) +* Exec prefix: Build Options. (line 32) +* Execution profiling: Build Options. (line 317) +* Execution profiling <1>: Profiling. (line 6) +* Exponentiation functions: Integer Exponentiation. + (line 6) +* Exponentiation functions <1>: Float Arithmetic. (line 41) +* Export: Integer Import and Export. + (line 45) +* Expression parsing demo: Demonstration Programs. + (line 15) +* Expression parsing demo <1>: Demonstration Programs. + (line 17) +* Expression parsing demo <2>: Demonstration Programs. + (line 19) +* Extended GCD: Number Theoretic Functions. + (line 56) +* Factor removal functions: Number Theoretic Functions. + (line 117) +* Factorial algorithm: Factorial Algorithm. (line 6) +* Factorial functions: Number Theoretic Functions. + (line 125) +* Factorization demo: Demonstration Programs. + (line 22) +* Fast Fourier Transform: FFT Multiplication. (line 6) +* Fat binary: Build Options. (line 160) +* FFT multiplication: Build Options. (line 307) +* FFT multiplication <1>: FFT Multiplication. (line 6) +* Fibonacci number algorithm: Fibonacci Numbers Algorithm. + (line 6) +* Fibonacci sequence functions: Number Theoretic Functions. + (line 145) +* Float arithmetic functions: Float Arithmetic. (line 6) +* Float assignment functions: Assigning Floats. (line 6) +* Float assignment functions <1>: Simultaneous Float Init & Assign. + (line 6) +* Float comparison functions: Float Comparison. (line 6) +* Float conversion functions: Converting Floats. (line 6) +* Float functions: Floating-point Functions. + (line 6) +* Float initialization functions: Initializing Floats. (line 6) +* Float initialization functions <1>: Simultaneous Float Init & Assign. + (line 6) +* Float input and output functions: I/O of Floats. (line 6) +* Float internals: Float Internals. (line 6) +* Float miscellaneous functions: Miscellaneous Float Functions. + (line 6) +* Float random number functions: Miscellaneous Float Functions. + (line 27) +* Float rounding functions: Miscellaneous Float Functions. + (line 9) +* Float sign tests: Float Comparison. (line 34) +* Floating point mode: Notes for Particular Systems. + (line 34) +* Floating-point functions: Floating-point Functions. + (line 6) +* Floating-point number: Nomenclature and Types. + (line 21) +* fnccheck: Profiling. (line 77) +* Formatted input: Formatted Input. (line 6) +* Formatted output: Formatted Output. (line 6) +* Free Documentation License: GNU Free Documentation License. + (line 6) +* FreeBSD: Notes for Particular Systems. + (line 43) +* FreeBSD <1>: Notes for Particular Systems. + (line 52) +* frexp: Converting Integers. (line 43) +* frexp <1>: Converting Floats. (line 24) +* FTP of latest version: Introduction to GMP. (line 37) +* Function classes: Function Classes. (line 6) +* FunctionCheck: Profiling. (line 77) +* GCC Checker: Debugging. (line 110) +* GCD algorithms: Greatest Common Divisor Algorithms. + (line 6) +* GCD extended: Number Theoretic Functions. + (line 56) +* GCD functions: Number Theoretic Functions. + (line 39) +* GDB: Debugging. (line 53) +* Generic C: Build Options. (line 151) +* GMP Perl module: Demonstration Programs. + (line 28) +* GMP version number: Useful Macros and Constants. + (line 12) +* gmp.h: Headers and Libraries. + (line 6) +* gmpxx.h: C++ Interface General. + (line 8) +* GNU Debugger: Debugging. (line 53) +* GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* GNU strip: Known Build Problems. + (line 28) +* gprof: Profiling. (line 41) +* Greatest common divisor algorithms: Greatest Common Divisor Algorithms. + (line 6) +* Greatest common divisor functions: Number Theoretic Functions. + (line 39) +* Hardware floating point mode: Notes for Particular Systems. + (line 34) +* Headers: Headers and Libraries. + (line 6) +* Heap problems: Debugging. (line 23) +* Home page: Introduction to GMP. (line 33) +* Host system: Build Options. (line 65) +* HP-UX: ABI and ISA. (line 76) +* HP-UX <1>: ABI and ISA. (line 114) +* HPPA: ABI and ISA. (line 76) +* I/O functions: I/O of Integers. (line 6) +* I/O functions <1>: I/O of Rationals. (line 6) +* I/O functions <2>: I/O of Floats. (line 6) +* i386: Notes for Particular Systems. + (line 150) +* IA-64: ABI and ISA. (line 114) +* Import: Integer Import and Export. + (line 11) +* In-place operations: Efficiency. (line 57) +* Include files: Headers and Libraries. + (line 6) +* info-lookup-symbol: Emacs. (line 6) +* Initialization functions: Initializing Integers. + (line 6) +* Initialization functions <1>: Simultaneous Integer Init & Assign. + (line 6) +* Initialization functions <2>: Initializing Rationals. + (line 6) +* Initialization functions <3>: Initializing Floats. (line 6) +* Initialization functions <4>: Simultaneous Float Init & Assign. + (line 6) +* Initialization functions <5>: Random State Initialization. + (line 6) +* Initializing and clearing: Efficiency. (line 21) +* Input functions: I/O of Integers. (line 6) +* Input functions <1>: I/O of Rationals. (line 6) +* Input functions <2>: I/O of Floats. (line 6) +* Input functions <3>: Formatted Input Functions. + (line 6) +* Install prefix: Build Options. (line 32) +* Installing GMP: Installing GMP. (line 6) +* Instruction Set Architecture: ABI and ISA. (line 6) +* instrument-functions: Profiling. (line 66) +* Integer: Nomenclature and Types. + (line 6) +* Integer arithmetic functions: Integer Arithmetic. (line 6) +* Integer assignment functions: Assigning Integers. (line 6) +* Integer assignment functions <1>: Simultaneous Integer Init & Assign. + (line 6) +* Integer bit manipulation functions: Integer Logic and Bit Fiddling. + (line 6) +* Integer comparison functions: Integer Comparisons. (line 6) +* Integer conversion functions: Converting Integers. (line 6) +* Integer division functions: Integer Division. (line 6) +* Integer exponentiation functions: Integer Exponentiation. + (line 6) +* Integer export: Integer Import and Export. + (line 45) +* Integer functions: Integer Functions. (line 6) +* Integer import: Integer Import and Export. + (line 11) +* Integer initialization functions: Initializing Integers. + (line 6) +* Integer initialization functions <1>: Simultaneous Integer Init & Assign. + (line 6) +* Integer input and output functions: I/O of Integers. (line 6) +* Integer internals: Integer Internals. (line 6) +* Integer logical functions: Integer Logic and Bit Fiddling. + (line 6) +* Integer miscellaneous functions: Miscellaneous Integer Functions. + (line 6) +* Integer random number functions: Integer Random Numbers. + (line 6) +* Integer root functions: Integer Roots. (line 6) +* Integer sign tests: Integer Comparisons. (line 28) +* Integer special functions: Integer Special Functions. + (line 6) +* Interix: Notes for Particular Systems. + (line 65) +* Internals: Internals. (line 6) +* Introduction: Introduction to GMP. (line 6) +* Inverse modulo functions: Number Theoretic Functions. + (line 83) +* IRIX: ABI and ISA. (line 139) +* IRIX <1>: Known Build Problems. + (line 38) +* ISA: ABI and ISA. (line 6) +* istream input: C++ Formatted Input. (line 6) +* Jacobi symbol algorithm: Jacobi Symbol. (line 6) +* Jacobi symbol functions: Number Theoretic Functions. + (line 92) +* Karatsuba multiplication: Karatsuba Multiplication. + (line 6) +* Karatsuba square root algorithm: Square Root Algorithm. + (line 6) +* Kronecker symbol functions: Number Theoretic Functions. + (line 104) +* Language bindings: Language Bindings. (line 6) +* Latest version of GMP: Introduction to GMP. (line 37) +* LCM functions: Number Theoretic Functions. + (line 77) +* Least common multiple functions: Number Theoretic Functions. + (line 77) +* Legendre symbol functions: Number Theoretic Functions. + (line 95) +* libgmp: Headers and Libraries. + (line 24) +* libgmpxx: Headers and Libraries. + (line 29) +* Libraries: Headers and Libraries. + (line 24) +* Libtool: Headers and Libraries. + (line 36) +* Libtool versioning: Notes for Package Builds. + (line 9) +* License conditions: Copying. (line 6) +* Limb: Nomenclature and Types. + (line 31) +* Limb size: Useful Macros and Constants. + (line 7) +* Linear congruential algorithm: Random Number Algorithms. + (line 25) +* Linear congruential random numbers: Random State Initialization. + (line 18) +* Linear congruential random numbers <1>: Random State Initialization. + (line 32) +* Linking: Headers and Libraries. + (line 24) +* Logical functions: Integer Logic and Bit Fiddling. + (line 6) +* Low-level functions: Low-level Functions. (line 6) +* Low-level functions for cryptography: Low-level Functions. (line 507) +* Lucas number algorithm: Lucas Numbers Algorithm. + (line 6) +* Lucas number functions: Number Theoretic Functions. + (line 156) +* MacOS X: Known Build Problems. + (line 51) +* Mailing lists: Introduction to GMP. (line 44) +* Malloc debugger: Debugging. (line 29) +* Malloc problems: Debugging. (line 23) +* Memory allocation: Custom Allocation. (line 6) +* Memory management: Memory Management. (line 6) +* Mersenne twister algorithm: Random Number Algorithms. + (line 17) +* Mersenne twister random numbers: Random State Initialization. + (line 13) +* MINGW: Notes for Particular Systems. + (line 57) +* MIPS: ABI and ISA. (line 139) +* Miscellaneous float functions: Miscellaneous Float Functions. + (line 6) +* Miscellaneous integer functions: Miscellaneous Integer Functions. + (line 6) +* MMX: Notes for Particular Systems. + (line 156) +* Modular inverse functions: Number Theoretic Functions. + (line 83) +* Most significant bit: Miscellaneous Integer Functions. + (line 34) +* MPN_PATH: Build Options. (line 321) +* MS Windows: Notes for Particular Systems. + (line 57) +* MS Windows <1>: Notes for Particular Systems. + (line 70) +* MS-DOS: Notes for Particular Systems. + (line 57) +* Multi-threading: Reentrancy. (line 6) +* Multiplication algorithms: Multiplication Algorithms. + (line 6) +* Nails: Low-level Functions. (line 686) +* Native compilation: Build Options. (line 51) +* NetBSD: Notes for Particular Systems. + (line 100) +* NeXT: Known Build Problems. + (line 57) +* Next prime function: Number Theoretic Functions. + (line 23) +* Nomenclature: Nomenclature and Types. + (line 6) +* Non-Unix systems: Build Options. (line 11) +* Nth root algorithm: Nth Root Algorithm. (line 6) +* Number sequences: Efficiency. (line 145) +* Number theoretic functions: Number Theoretic Functions. + (line 6) +* Numerator and denominator: Applying Integer Functions. + (line 6) +* obstack output: Formatted Output Functions. + (line 79) +* OpenBSD: Notes for Particular Systems. + (line 109) +* Optimizing performance: Performance optimization. + (line 6) +* ostream output: C++ Formatted Output. + (line 6) +* Other languages: Language Bindings. (line 6) +* Output functions: I/O of Integers. (line 6) +* Output functions <1>: I/O of Rationals. (line 6) +* Output functions <2>: I/O of Floats. (line 6) +* Output functions <3>: Formatted Output Functions. + (line 6) +* Packaged builds: Notes for Package Builds. + (line 6) +* Parameter conventions: Parameter Conventions. + (line 6) +* Parsing expressions demo: Demonstration Programs. + (line 15) +* Parsing expressions demo <1>: Demonstration Programs. + (line 17) +* Parsing expressions demo <2>: Demonstration Programs. + (line 19) +* Particular systems: Notes for Particular Systems. + (line 6) +* Past GMP versions: Compatibility with older versions. + (line 6) +* PDF: Build Options. (line 336) +* Perfect power algorithm: Perfect Power Algorithm. + (line 6) +* Perfect power functions: Integer Roots. (line 28) +* Perfect square algorithm: Perfect Square Algorithm. + (line 6) +* Perfect square functions: Integer Roots. (line 37) +* perl: Demonstration Programs. + (line 28) +* Perl module: Demonstration Programs. + (line 28) +* Pointer types: Nomenclature and Types. + (line 55) +* Postscript: Build Options. (line 336) +* Power/PowerPC: Notes for Particular Systems. + (line 115) +* Power/PowerPC <1>: Known Build Problems. + (line 63) +* Powering algorithms: Powering Algorithms. (line 6) +* Powering functions: Integer Exponentiation. + (line 6) +* Powering functions <1>: Float Arithmetic. (line 41) +* PowerPC: ABI and ISA. (line 173) +* Precision of floats: Floating-point Functions. + (line 6) +* Precision of hardware floating point: Notes for Particular Systems. + (line 34) +* Prefix: Build Options. (line 32) +* Previous prime function: Number Theoretic Functions. + (line 26) +* Prime testing algorithms: Prime Testing Algorithm. + (line 6) +* Prime testing functions: Number Theoretic Functions. + (line 7) +* Primorial functions: Number Theoretic Functions. + (line 130) +* printf formatted output: Formatted Output. (line 6) +* Probable prime testing functions: Number Theoretic Functions. + (line 7) +* prof: Profiling. (line 24) +* Profiling: Profiling. (line 6) +* Radix conversion algorithms: Radix Conversion Algorithms. + (line 6) +* Random number algorithms: Random Number Algorithms. + (line 6) +* Random number functions: Integer Random Numbers. + (line 6) +* Random number functions <1>: Miscellaneous Float Functions. + (line 27) +* Random number functions <2>: Random Number Functions. + (line 6) +* Random number seeding: Random State Seeding. + (line 6) +* Random number state: Random State Initialization. + (line 6) +* Random state: Nomenclature and Types. + (line 46) +* Rational arithmetic: Efficiency. (line 111) +* Rational arithmetic functions: Rational Arithmetic. (line 6) +* Rational assignment functions: Initializing Rationals. + (line 6) +* Rational comparison functions: Comparing Rationals. (line 6) +* Rational conversion functions: Rational Conversions. + (line 6) +* Rational initialization functions: Initializing Rationals. + (line 6) +* Rational input and output functions: I/O of Rationals. (line 6) +* Rational internals: Rational Internals. (line 6) +* Rational number: Nomenclature and Types. + (line 16) +* Rational number functions: Rational Number Functions. + (line 6) +* Rational numerator and denominator: Applying Integer Functions. + (line 6) +* Rational sign tests: Comparing Rationals. (line 28) +* Raw output internals: Raw Output Internals. + (line 6) +* Reallocations: Efficiency. (line 30) +* Reentrancy: Reentrancy. (line 6) +* References: References. (line 5) +* Remove factor functions: Number Theoretic Functions. + (line 117) +* Reporting bugs: Reporting Bugs. (line 6) +* Root extraction algorithm: Nth Root Algorithm. (line 6) +* Root extraction algorithms: Root Extraction Algorithms. + (line 6) +* Root extraction functions: Integer Roots. (line 6) +* Root extraction functions <1>: Float Arithmetic. (line 37) +* Root testing functions: Integer Roots. (line 28) +* Root testing functions <1>: Integer Roots. (line 37) +* Rounding functions: Miscellaneous Float Functions. + (line 9) +* Sample programs: Demonstration Programs. + (line 6) +* Scan bit functions: Integer Logic and Bit Fiddling. + (line 39) +* scanf formatted input: Formatted Input. (line 6) +* SCO: Known Build Problems. + (line 38) +* Seeding random numbers: Random State Seeding. + (line 6) +* Segmentation violation: Debugging. (line 7) +* Sequent Symmetry: Known Build Problems. + (line 68) +* Services for Unix: Notes for Particular Systems. + (line 65) +* Shared library versioning: Notes for Package Builds. + (line 9) +* Sign tests: Integer Comparisons. (line 28) +* Sign tests <1>: Comparing Rationals. (line 28) +* Sign tests <2>: Float Comparison. (line 34) +* Size in digits: Miscellaneous Integer Functions. + (line 23) +* Small operands: Efficiency. (line 7) +* Solaris: ABI and ISA. (line 204) +* Solaris <1>: Known Build Problems. + (line 72) +* Solaris <2>: Known Build Problems. + (line 77) +* Sparc: Notes for Particular Systems. + (line 127) +* Sparc <1>: Notes for Particular Systems. + (line 132) +* Sparc V9: ABI and ISA. (line 204) +* Special integer functions: Integer Special Functions. + (line 6) +* Square root algorithm: Square Root Algorithm. + (line 6) +* SSE2: Notes for Particular Systems. + (line 156) +* Stack backtrace: Debugging. (line 45) +* Stack overflow: Build Options. (line 273) +* Stack overflow <1>: Debugging. (line 7) +* Static linking: Efficiency. (line 14) +* stdarg.h: Headers and Libraries. + (line 19) +* stdio.h: Headers and Libraries. + (line 13) +* Stripped libraries: Known Build Problems. + (line 28) +* Sun: ABI and ISA. (line 204) +* SunOS: Notes for Particular Systems. + (line 144) +* Systems: Notes for Particular Systems. + (line 6) +* Temporary memory: Build Options. (line 273) +* Texinfo: Build Options. (line 333) +* Text input/output: Efficiency. (line 151) +* Thread safety: Reentrancy. (line 6) +* Toom multiplication: Toom 3-Way Multiplication. + (line 6) +* Toom multiplication <1>: Toom 4-Way Multiplication. + (line 6) +* Toom multiplication <2>: Higher degree Toom'n'half. + (line 6) +* Toom multiplication <3>: Other Multiplication. + (line 6) +* Types: Nomenclature and Types. + (line 6) +* ui and si functions: Efficiency. (line 50) +* Unbalanced multiplication: Unbalanced Multiplication. + (line 6) +* Upward compatibility: Compatibility with older versions. + (line 6) +* Useful macros and constants: Useful Macros and Constants. + (line 6) +* User-defined precision: Floating-point Functions. + (line 6) +* Valgrind: Debugging. (line 125) +* Variable conventions: Variable Conventions. + (line 6) +* Version number: Useful Macros and Constants. + (line 12) +* Web page: Introduction to GMP. (line 33) +* Windows: Notes for Particular Systems. + (line 57) +* Windows <1>: Notes for Particular Systems. + (line 70) +* x86: Notes for Particular Systems. + (line 150) +* x87: Notes for Particular Systems. + (line 34) +* XML: Build Options. (line 340) + + +File: gmp.info, Node: Function Index, Prev: Concept Index, Up: Top + +Function and Type Index +*********************** + +[index] +* Menu: + +* _mpz_realloc: Integer Special Functions. + (line 13) +* __GMP_CC: Useful Macros and Constants. + (line 22) +* __GMP_CFLAGS: Useful Macros and Constants. + (line 23) +* __GNU_MP_VERSION: Useful Macros and Constants. + (line 9) +* __GNU_MP_VERSION_MINOR: Useful Macros and Constants. + (line 10) +* __GNU_MP_VERSION_PATCHLEVEL: Useful Macros and Constants. + (line 11) +* abs: C++ Interface Integers. + (line 46) +* abs <1>: C++ Interface Rationals. + (line 47) +* abs <2>: C++ Interface Floats. + (line 82) +* ceil: C++ Interface Floats. + (line 83) +* cmp: C++ Interface Integers. + (line 47) +* cmp <1>: C++ Interface Integers. + (line 48) +* cmp <2>: C++ Interface Rationals. + (line 48) +* cmp <3>: C++ Interface Rationals. + (line 49) +* cmp <4>: C++ Interface Floats. + (line 84) +* cmp <5>: C++ Interface Floats. + (line 85) +* factorial: C++ Interface Integers. + (line 71) +* fibonacci: C++ Interface Integers. + (line 75) +* floor: C++ Interface Floats. + (line 95) +* gcd: C++ Interface Integers. + (line 68) +* gmp_asprintf: Formatted Output Functions. + (line 63) +* gmp_errno: Random State Initialization. + (line 56) +* GMP_ERROR_INVALID_ARGUMENT: Random State Initialization. + (line 56) +* GMP_ERROR_UNSUPPORTED_ARGUMENT: Random State Initialization. + (line 56) +* gmp_fprintf: Formatted Output Functions. + (line 28) +* gmp_fscanf: Formatted Input Functions. + (line 24) +* GMP_LIMB_BITS: Low-level Functions. (line 714) +* GMP_NAIL_BITS: Low-level Functions. (line 712) +* GMP_NAIL_MASK: Low-level Functions. (line 722) +* GMP_NUMB_BITS: Low-level Functions. (line 713) +* GMP_NUMB_MASK: Low-level Functions. (line 723) +* GMP_NUMB_MAX: Low-level Functions. (line 731) +* gmp_obstack_printf: Formatted Output Functions. + (line 75) +* gmp_obstack_vprintf: Formatted Output Functions. + (line 77) +* gmp_printf: Formatted Output Functions. + (line 23) +* gmp_randclass: C++ Interface Random Numbers. + (line 6) +* gmp_randclass::get_f: C++ Interface Random Numbers. + (line 44) +* gmp_randclass::get_f <1>: C++ Interface Random Numbers. + (line 45) +* gmp_randclass::get_z_bits: C++ Interface Random Numbers. + (line 37) +* gmp_randclass::get_z_bits <1>: C++ Interface Random Numbers. + (line 38) +* gmp_randclass::get_z_range: C++ Interface Random Numbers. + (line 41) +* gmp_randclass::gmp_randclass: C++ Interface Random Numbers. + (line 11) +* gmp_randclass::gmp_randclass <1>: C++ Interface Random Numbers. + (line 26) +* gmp_randclass::seed: C++ Interface Random Numbers. + (line 32) +* gmp_randclass::seed <1>: C++ Interface Random Numbers. + (line 33) +* gmp_randclear: Random State Initialization. + (line 62) +* gmp_randinit: Random State Initialization. + (line 45) +* gmp_randinit_default: Random State Initialization. + (line 6) +* gmp_randinit_lc_2exp: Random State Initialization. + (line 16) +* gmp_randinit_lc_2exp_size: Random State Initialization. + (line 30) +* gmp_randinit_mt: Random State Initialization. + (line 12) +* gmp_randinit_set: Random State Initialization. + (line 41) +* gmp_randseed: Random State Seeding. + (line 6) +* gmp_randseed_ui: Random State Seeding. + (line 8) +* gmp_randstate_ptr: Nomenclature and Types. + (line 55) +* gmp_randstate_srcptr: Nomenclature and Types. + (line 55) +* gmp_randstate_t: Nomenclature and Types. + (line 46) +* GMP_RAND_ALG_DEFAULT: Random State Initialization. + (line 50) +* GMP_RAND_ALG_LC: Random State Initialization. + (line 50) +* gmp_scanf: Formatted Input Functions. + (line 20) +* gmp_snprintf: Formatted Output Functions. + (line 44) +* gmp_sprintf: Formatted Output Functions. + (line 33) +* gmp_sscanf: Formatted Input Functions. + (line 28) +* gmp_urandomb_ui: Random State Miscellaneous. + (line 6) +* gmp_urandomm_ui: Random State Miscellaneous. + (line 12) +* gmp_vasprintf: Formatted Output Functions. + (line 64) +* gmp_version: Useful Macros and Constants. + (line 18) +* gmp_vfprintf: Formatted Output Functions. + (line 29) +* gmp_vfscanf: Formatted Input Functions. + (line 25) +* gmp_vprintf: Formatted Output Functions. + (line 24) +* gmp_vscanf: Formatted Input Functions. + (line 21) +* gmp_vsnprintf: Formatted Output Functions. + (line 46) +* gmp_vsprintf: Formatted Output Functions. + (line 34) +* gmp_vsscanf: Formatted Input Functions. + (line 29) +* hypot: C++ Interface Floats. + (line 96) +* lcm: C++ Interface Integers. + (line 69) +* mpf_abs: Float Arithmetic. (line 46) +* mpf_add: Float Arithmetic. (line 6) +* mpf_add_ui: Float Arithmetic. (line 7) +* mpf_ceil: Miscellaneous Float Functions. + (line 6) +* mpf_class: C++ Interface General. + (line 19) +* mpf_class::fits_sint_p: C++ Interface Floats. + (line 87) +* mpf_class::fits_slong_p: C++ Interface Floats. + (line 88) +* mpf_class::fits_sshort_p: C++ Interface Floats. + (line 89) +* mpf_class::fits_uint_p: C++ Interface Floats. + (line 91) +* mpf_class::fits_ulong_p: C++ Interface Floats. + (line 92) +* mpf_class::fits_ushort_p: C++ Interface Floats. + (line 93) +* mpf_class::get_d: C++ Interface Floats. + (line 98) +* mpf_class::get_mpf_t: C++ Interface General. + (line 65) +* mpf_class::get_prec: C++ Interface Floats. + (line 120) +* mpf_class::get_si: C++ Interface Floats. + (line 99) +* mpf_class::get_str: C++ Interface Floats. + (line 100) +* mpf_class::get_ui: C++ Interface Floats. + (line 102) +* mpf_class::mpf_class: C++ Interface Floats. + (line 11) +* mpf_class::mpf_class <1>: C++ Interface Floats. + (line 12) +* mpf_class::mpf_class <2>: C++ Interface Floats. + (line 32) +* mpf_class::mpf_class <3>: C++ Interface Floats. + (line 33) +* mpf_class::mpf_class <4>: C++ Interface Floats. + (line 41) +* mpf_class::mpf_class <5>: C++ Interface Floats. + (line 42) +* mpf_class::mpf_class <6>: C++ Interface Floats. + (line 44) +* mpf_class::mpf_class <7>: C++ Interface Floats. + (line 45) +* mpf_class::operator=: C++ Interface Floats. + (line 59) +* mpf_class::set_prec: C++ Interface Floats. + (line 121) +* mpf_class::set_prec_raw: C++ Interface Floats. + (line 122) +* mpf_class::set_str: C++ Interface Floats. + (line 104) +* mpf_class::set_str <1>: C++ Interface Floats. + (line 105) +* mpf_class::swap: C++ Interface Floats. + (line 109) +* mpf_clear: Initializing Floats. (line 36) +* mpf_clears: Initializing Floats. (line 40) +* mpf_cmp: Float Comparison. (line 6) +* mpf_cmp_d: Float Comparison. (line 8) +* mpf_cmp_si: Float Comparison. (line 10) +* mpf_cmp_ui: Float Comparison. (line 9) +* mpf_cmp_z: Float Comparison. (line 7) +* mpf_div: Float Arithmetic. (line 28) +* mpf_div_2exp: Float Arithmetic. (line 53) +* mpf_div_ui: Float Arithmetic. (line 31) +* mpf_eq: Float Comparison. (line 17) +* mpf_fits_sint_p: Miscellaneous Float Functions. + (line 19) +* mpf_fits_slong_p: Miscellaneous Float Functions. + (line 17) +* mpf_fits_sshort_p: Miscellaneous Float Functions. + (line 21) +* mpf_fits_uint_p: Miscellaneous Float Functions. + (line 18) +* mpf_fits_ulong_p: Miscellaneous Float Functions. + (line 16) +* mpf_fits_ushort_p: Miscellaneous Float Functions. + (line 20) +* mpf_floor: Miscellaneous Float Functions. + (line 7) +* mpf_get_d: Converting Floats. (line 6) +* mpf_get_default_prec: Initializing Floats. (line 11) +* mpf_get_d_2exp: Converting Floats. (line 15) +* mpf_get_prec: Initializing Floats. (line 61) +* mpf_get_si: Converting Floats. (line 27) +* mpf_get_str: Converting Floats. (line 36) +* mpf_get_ui: Converting Floats. (line 28) +* mpf_init: Initializing Floats. (line 18) +* mpf_init2: Initializing Floats. (line 25) +* mpf_inits: Initializing Floats. (line 30) +* mpf_init_set: Simultaneous Float Init & Assign. + (line 15) +* mpf_init_set_d: Simultaneous Float Init & Assign. + (line 18) +* mpf_init_set_si: Simultaneous Float Init & Assign. + (line 17) +* mpf_init_set_str: Simultaneous Float Init & Assign. + (line 24) +* mpf_init_set_ui: Simultaneous Float Init & Assign. + (line 16) +* mpf_inp_str: I/O of Floats. (line 38) +* mpf_integer_p: Miscellaneous Float Functions. + (line 13) +* mpf_mul: Float Arithmetic. (line 18) +* mpf_mul_2exp: Float Arithmetic. (line 49) +* mpf_mul_ui: Float Arithmetic. (line 19) +* mpf_neg: Float Arithmetic. (line 43) +* mpf_out_str: I/O of Floats. (line 17) +* mpf_pow_ui: Float Arithmetic. (line 39) +* mpf_ptr: Nomenclature and Types. + (line 55) +* mpf_random2: Miscellaneous Float Functions. + (line 35) +* mpf_reldiff: Float Comparison. (line 28) +* mpf_set: Assigning Floats. (line 9) +* mpf_set_d: Assigning Floats. (line 12) +* mpf_set_default_prec: Initializing Floats. (line 6) +* mpf_set_prec: Initializing Floats. (line 64) +* mpf_set_prec_raw: Initializing Floats. (line 71) +* mpf_set_q: Assigning Floats. (line 14) +* mpf_set_si: Assigning Floats. (line 11) +* mpf_set_str: Assigning Floats. (line 17) +* mpf_set_ui: Assigning Floats. (line 10) +* mpf_set_z: Assigning Floats. (line 13) +* mpf_sgn: Float Comparison. (line 33) +* mpf_sqrt: Float Arithmetic. (line 35) +* mpf_sqrt_ui: Float Arithmetic. (line 36) +* mpf_srcptr: Nomenclature and Types. + (line 55) +* mpf_sub: Float Arithmetic. (line 11) +* mpf_sub_ui: Float Arithmetic. (line 14) +* mpf_swap: Assigning Floats. (line 50) +* mpf_t: Nomenclature and Types. + (line 21) +* mpf_trunc: Miscellaneous Float Functions. + (line 8) +* mpf_ui_div: Float Arithmetic. (line 29) +* mpf_ui_sub: Float Arithmetic. (line 12) +* mpf_urandomb: Miscellaneous Float Functions. + (line 25) +* mpn_add: Low-level Functions. (line 67) +* mpn_addmul_1: Low-level Functions. (line 148) +* mpn_add_1: Low-level Functions. (line 62) +* mpn_add_n: Low-level Functions. (line 52) +* mpn_andn_n: Low-level Functions. (line 462) +* mpn_and_n: Low-level Functions. (line 447) +* mpn_cmp: Low-level Functions. (line 293) +* mpn_cnd_add_n: Low-level Functions. (line 540) +* mpn_cnd_sub_n: Low-level Functions. (line 542) +* mpn_cnd_swap: Low-level Functions. (line 567) +* mpn_com: Low-level Functions. (line 487) +* mpn_copyd: Low-level Functions. (line 496) +* mpn_copyi: Low-level Functions. (line 492) +* mpn_divexact_1: Low-level Functions. (line 231) +* mpn_divexact_by3: Low-level Functions. (line 238) +* mpn_divexact_by3c: Low-level Functions. (line 240) +* mpn_divmod: Low-level Functions. (line 226) +* mpn_divmod_1: Low-level Functions. (line 210) +* mpn_divrem: Low-level Functions. (line 183) +* mpn_divrem_1: Low-level Functions. (line 208) +* mpn_gcd: Low-level Functions. (line 301) +* mpn_gcdext: Low-level Functions. (line 316) +* mpn_gcd_1: Low-level Functions. (line 311) +* mpn_get_str: Low-level Functions. (line 371) +* mpn_hamdist: Low-level Functions. (line 436) +* mpn_iorn_n: Low-level Functions. (line 467) +* mpn_ior_n: Low-level Functions. (line 452) +* mpn_lshift: Low-level Functions. (line 269) +* mpn_mod_1: Low-level Functions. (line 264) +* mpn_mul: Low-level Functions. (line 114) +* mpn_mul_1: Low-level Functions. (line 133) +* mpn_mul_n: Low-level Functions. (line 103) +* mpn_nand_n: Low-level Functions. (line 472) +* mpn_neg: Low-level Functions. (line 96) +* mpn_nior_n: Low-level Functions. (line 477) +* mpn_perfect_square_p: Low-level Functions. (line 442) +* mpn_popcount: Low-level Functions. (line 432) +* mpn_random: Low-level Functions. (line 422) +* mpn_random2: Low-level Functions. (line 423) +* mpn_rshift: Low-level Functions. (line 281) +* mpn_scan0: Low-level Functions. (line 406) +* mpn_scan1: Low-level Functions. (line 414) +* mpn_sec_add_1: Low-level Functions. (line 553) +* mpn_sec_div_qr: Low-level Functions. (line 630) +* mpn_sec_div_qr_itch: Low-level Functions. (line 633) +* mpn_sec_div_r: Low-level Functions. (line 649) +* mpn_sec_div_r_itch: Low-level Functions. (line 651) +* mpn_sec_invert: Low-level Functions. (line 665) +* mpn_sec_invert_itch: Low-level Functions. (line 667) +* mpn_sec_mul: Low-level Functions. (line 574) +* mpn_sec_mul_itch: Low-level Functions. (line 577) +* mpn_sec_powm: Low-level Functions. (line 604) +* mpn_sec_powm_itch: Low-level Functions. (line 607) +* mpn_sec_sqr: Low-level Functions. (line 590) +* mpn_sec_sqr_itch: Low-level Functions. (line 592) +* mpn_sec_sub_1: Low-level Functions. (line 555) +* mpn_sec_tabselect: Low-level Functions. (line 622) +* mpn_set_str: Low-level Functions. (line 386) +* mpn_sizeinbase: Low-level Functions. (line 364) +* mpn_sqr: Low-level Functions. (line 125) +* mpn_sqrtrem: Low-level Functions. (line 346) +* mpn_sub: Low-level Functions. (line 88) +* mpn_submul_1: Low-level Functions. (line 160) +* mpn_sub_1: Low-level Functions. (line 83) +* mpn_sub_n: Low-level Functions. (line 74) +* mpn_tdiv_qr: Low-level Functions. (line 172) +* mpn_xnor_n: Low-level Functions. (line 482) +* mpn_xor_n: Low-level Functions. (line 457) +* mpn_zero: Low-level Functions. (line 500) +* mpn_zero_p: Low-level Functions. (line 298) +* mpq_abs: Rational Arithmetic. (line 33) +* mpq_add: Rational Arithmetic. (line 6) +* mpq_canonicalize: Rational Number Functions. + (line 21) +* mpq_class: C++ Interface General. + (line 18) +* mpq_class::canonicalize: C++ Interface Rationals. + (line 41) +* mpq_class::get_d: C++ Interface Rationals. + (line 51) +* mpq_class::get_den: C++ Interface Rationals. + (line 67) +* mpq_class::get_den_mpz_t: C++ Interface Rationals. + (line 77) +* mpq_class::get_mpq_t: C++ Interface General. + (line 64) +* mpq_class::get_num: C++ Interface Rationals. + (line 66) +* mpq_class::get_num_mpz_t: C++ Interface Rationals. + (line 76) +* mpq_class::get_str: C++ Interface Rationals. + (line 52) +* mpq_class::mpq_class: C++ Interface Rationals. + (line 9) +* mpq_class::mpq_class <1>: C++ Interface Rationals. + (line 10) +* mpq_class::mpq_class <2>: C++ Interface Rationals. + (line 21) +* mpq_class::mpq_class <3>: C++ Interface Rationals. + (line 26) +* mpq_class::mpq_class <4>: C++ Interface Rationals. + (line 28) +* mpq_class::set_str: C++ Interface Rationals. + (line 54) +* mpq_class::set_str <1>: C++ Interface Rationals. + (line 55) +* mpq_class::swap: C++ Interface Rationals. + (line 58) +* mpq_clear: Initializing Rationals. + (line 15) +* mpq_clears: Initializing Rationals. + (line 19) +* mpq_cmp: Comparing Rationals. (line 6) +* mpq_cmp_si: Comparing Rationals. (line 16) +* mpq_cmp_ui: Comparing Rationals. (line 14) +* mpq_cmp_z: Comparing Rationals. (line 7) +* mpq_denref: Applying Integer Functions. + (line 16) +* mpq_div: Rational Arithmetic. (line 22) +* mpq_div_2exp: Rational Arithmetic. (line 26) +* mpq_equal: Comparing Rationals. (line 33) +* mpq_get_d: Rational Conversions. + (line 6) +* mpq_get_den: Applying Integer Functions. + (line 24) +* mpq_get_num: Applying Integer Functions. + (line 23) +* mpq_get_str: Rational Conversions. + (line 21) +* mpq_init: Initializing Rationals. + (line 6) +* mpq_inits: Initializing Rationals. + (line 11) +* mpq_inp_str: I/O of Rationals. (line 32) +* mpq_inv: Rational Arithmetic. (line 36) +* mpq_mul: Rational Arithmetic. (line 14) +* mpq_mul_2exp: Rational Arithmetic. (line 18) +* mpq_neg: Rational Arithmetic. (line 30) +* mpq_numref: Applying Integer Functions. + (line 15) +* mpq_out_str: I/O of Rationals. (line 17) +* mpq_ptr: Nomenclature and Types. + (line 55) +* mpq_set: Initializing Rationals. + (line 23) +* mpq_set_d: Rational Conversions. + (line 16) +* mpq_set_den: Applying Integer Functions. + (line 26) +* mpq_set_f: Rational Conversions. + (line 17) +* mpq_set_num: Applying Integer Functions. + (line 25) +* mpq_set_si: Initializing Rationals. + (line 29) +* mpq_set_str: Initializing Rationals. + (line 35) +* mpq_set_ui: Initializing Rationals. + (line 27) +* mpq_set_z: Initializing Rationals. + (line 24) +* mpq_sgn: Comparing Rationals. (line 27) +* mpq_srcptr: Nomenclature and Types. + (line 55) +* mpq_sub: Rational Arithmetic. (line 10) +* mpq_swap: Initializing Rationals. + (line 54) +* mpq_t: Nomenclature and Types. + (line 16) +* mpz_2fac_ui: Number Theoretic Functions. + (line 122) +* mpz_abs: Integer Arithmetic. (line 44) +* mpz_add: Integer Arithmetic. (line 6) +* mpz_addmul: Integer Arithmetic. (line 24) +* mpz_addmul_ui: Integer Arithmetic. (line 26) +* mpz_add_ui: Integer Arithmetic. (line 7) +* mpz_and: Integer Logic and Bit Fiddling. + (line 10) +* mpz_array_init: Integer Special Functions. + (line 9) +* mpz_bin_ui: Number Theoretic Functions. + (line 133) +* mpz_bin_uiui: Number Theoretic Functions. + (line 135) +* mpz_cdiv_q: Integer Division. (line 12) +* mpz_cdiv_qr: Integer Division. (line 14) +* mpz_cdiv_qr_ui: Integer Division. (line 21) +* mpz_cdiv_q_2exp: Integer Division. (line 26) +* mpz_cdiv_q_ui: Integer Division. (line 17) +* mpz_cdiv_r: Integer Division. (line 13) +* mpz_cdiv_r_2exp: Integer Division. (line 29) +* mpz_cdiv_r_ui: Integer Division. (line 19) +* mpz_cdiv_ui: Integer Division. (line 23) +* mpz_class: C++ Interface General. + (line 17) +* mpz_class::factorial: C++ Interface Integers. + (line 70) +* mpz_class::fibonacci: C++ Interface Integers. + (line 74) +* mpz_class::fits_sint_p: C++ Interface Integers. + (line 50) +* mpz_class::fits_slong_p: C++ Interface Integers. + (line 51) +* mpz_class::fits_sshort_p: C++ Interface Integers. + (line 52) +* mpz_class::fits_uint_p: C++ Interface Integers. + (line 54) +* mpz_class::fits_ulong_p: C++ Interface Integers. + (line 55) +* mpz_class::fits_ushort_p: C++ Interface Integers. + (line 56) +* mpz_class::get_d: C++ Interface Integers. + (line 58) +* mpz_class::get_mpz_t: C++ Interface General. + (line 63) +* mpz_class::get_si: C++ Interface Integers. + (line 59) +* mpz_class::get_str: C++ Interface Integers. + (line 60) +* mpz_class::get_ui: C++ Interface Integers. + (line 61) +* mpz_class::mpz_class: C++ Interface Integers. + (line 6) +* mpz_class::mpz_class <1>: C++ Interface Integers. + (line 14) +* mpz_class::mpz_class <2>: C++ Interface Integers. + (line 19) +* mpz_class::mpz_class <3>: C++ Interface Integers. + (line 21) +* mpz_class::primorial: C++ Interface Integers. + (line 72) +* mpz_class::set_str: C++ Interface Integers. + (line 63) +* mpz_class::set_str <1>: C++ Interface Integers. + (line 64) +* mpz_class::swap: C++ Interface Integers. + (line 77) +* mpz_clear: Initializing Integers. + (line 48) +* mpz_clears: Initializing Integers. + (line 52) +* mpz_clrbit: Integer Logic and Bit Fiddling. + (line 54) +* mpz_cmp: Integer Comparisons. (line 6) +* mpz_cmpabs: Integer Comparisons. (line 17) +* mpz_cmpabs_d: Integer Comparisons. (line 18) +* mpz_cmpabs_ui: Integer Comparisons. (line 19) +* mpz_cmp_d: Integer Comparisons. (line 7) +* mpz_cmp_si: Integer Comparisons. (line 8) +* mpz_cmp_ui: Integer Comparisons. (line 9) +* mpz_com: Integer Logic and Bit Fiddling. + (line 19) +* mpz_combit: Integer Logic and Bit Fiddling. + (line 57) +* mpz_congruent_2exp_p: Integer Division. (line 148) +* mpz_congruent_p: Integer Division. (line 144) +* mpz_congruent_ui_p: Integer Division. (line 146) +* mpz_divexact: Integer Division. (line 122) +* mpz_divexact_ui: Integer Division. (line 123) +* mpz_divisible_2exp_p: Integer Division. (line 135) +* mpz_divisible_p: Integer Division. (line 132) +* mpz_divisible_ui_p: Integer Division. (line 133) +* mpz_even_p: Miscellaneous Integer Functions. + (line 17) +* mpz_export: Integer Import and Export. + (line 43) +* mpz_fac_ui: Number Theoretic Functions. + (line 121) +* mpz_fdiv_q: Integer Division. (line 33) +* mpz_fdiv_qr: Integer Division. (line 35) +* mpz_fdiv_qr_ui: Integer Division. (line 42) +* mpz_fdiv_q_2exp: Integer Division. (line 47) +* mpz_fdiv_q_ui: Integer Division. (line 38) +* mpz_fdiv_r: Integer Division. (line 34) +* mpz_fdiv_r_2exp: Integer Division. (line 50) +* mpz_fdiv_r_ui: Integer Division. (line 40) +* mpz_fdiv_ui: Integer Division. (line 44) +* mpz_fib2_ui: Number Theoretic Functions. + (line 143) +* mpz_fib_ui: Number Theoretic Functions. + (line 142) +* mpz_fits_sint_p: Miscellaneous Integer Functions. + (line 9) +* mpz_fits_slong_p: Miscellaneous Integer Functions. + (line 7) +* mpz_fits_sshort_p: Miscellaneous Integer Functions. + (line 11) +* mpz_fits_uint_p: Miscellaneous Integer Functions. + (line 8) +* mpz_fits_ulong_p: Miscellaneous Integer Functions. + (line 6) +* mpz_fits_ushort_p: Miscellaneous Integer Functions. + (line 10) +* mpz_gcd: Number Theoretic Functions. + (line 38) +* mpz_gcdext: Number Theoretic Functions. + (line 54) +* mpz_gcd_ui: Number Theoretic Functions. + (line 44) +* mpz_getlimbn: Integer Special Functions. + (line 22) +* mpz_get_d: Converting Integers. (line 26) +* mpz_get_d_2exp: Converting Integers. (line 34) +* mpz_get_si: Converting Integers. (line 17) +* mpz_get_str: Converting Integers. (line 46) +* mpz_get_ui: Converting Integers. (line 10) +* mpz_hamdist: Integer Logic and Bit Fiddling. + (line 28) +* mpz_import: Integer Import and Export. + (line 9) +* mpz_init: Initializing Integers. + (line 25) +* mpz_init2: Initializing Integers. + (line 32) +* mpz_inits: Initializing Integers. + (line 28) +* mpz_init_set: Simultaneous Integer Init & Assign. + (line 26) +* mpz_init_set_d: Simultaneous Integer Init & Assign. + (line 29) +* mpz_init_set_si: Simultaneous Integer Init & Assign. + (line 28) +* mpz_init_set_str: Simultaneous Integer Init & Assign. + (line 33) +* mpz_init_set_ui: Simultaneous Integer Init & Assign. + (line 27) +* mpz_inp_raw: I/O of Integers. (line 61) +* mpz_inp_str: I/O of Integers. (line 30) +* mpz_invert: Number Theoretic Functions. + (line 81) +* mpz_ior: Integer Logic and Bit Fiddling. + (line 13) +* mpz_jacobi: Number Theoretic Functions. + (line 91) +* mpz_kronecker: Number Theoretic Functions. + (line 99) +* mpz_kronecker_si: Number Theoretic Functions. + (line 100) +* mpz_kronecker_ui: Number Theoretic Functions. + (line 101) +* mpz_lcm: Number Theoretic Functions. + (line 74) +* mpz_lcm_ui: Number Theoretic Functions. + (line 75) +* mpz_legendre: Number Theoretic Functions. + (line 94) +* mpz_limbs_finish: Integer Special Functions. + (line 47) +* mpz_limbs_modify: Integer Special Functions. + (line 40) +* mpz_limbs_read: Integer Special Functions. + (line 34) +* mpz_limbs_write: Integer Special Functions. + (line 39) +* mpz_lucnum2_ui: Number Theoretic Functions. + (line 154) +* mpz_lucnum_ui: Number Theoretic Functions. + (line 153) +* mpz_mfac_uiui: Number Theoretic Functions. + (line 123) +* mpz_mod: Integer Division. (line 112) +* mpz_mod_ui: Integer Division. (line 113) +* mpz_mul: Integer Arithmetic. (line 18) +* mpz_mul_2exp: Integer Arithmetic. (line 36) +* mpz_mul_si: Integer Arithmetic. (line 19) +* mpz_mul_ui: Integer Arithmetic. (line 20) +* mpz_neg: Integer Arithmetic. (line 41) +* mpz_nextprime: Number Theoretic Functions. + (line 22) +* mpz_odd_p: Miscellaneous Integer Functions. + (line 16) +* mpz_out_raw: I/O of Integers. (line 45) +* mpz_out_str: I/O of Integers. (line 17) +* mpz_perfect_power_p: Integer Roots. (line 27) +* mpz_perfect_square_p: Integer Roots. (line 36) +* mpz_popcount: Integer Logic and Bit Fiddling. + (line 22) +* mpz_powm: Integer Exponentiation. + (line 6) +* mpz_powm_sec: Integer Exponentiation. + (line 16) +* mpz_powm_ui: Integer Exponentiation. + (line 8) +* mpz_pow_ui: Integer Exponentiation. + (line 29) +* mpz_prevprime: Number Theoretic Functions. + (line 25) +* mpz_primorial_ui: Number Theoretic Functions. + (line 129) +* mpz_probab_prime_p: Number Theoretic Functions. + (line 6) +* mpz_ptr: Nomenclature and Types. + (line 55) +* mpz_random: Integer Random Numbers. + (line 41) +* mpz_random2: Integer Random Numbers. + (line 50) +* mpz_realloc2: Initializing Integers. + (line 56) +* mpz_remove: Number Theoretic Functions. + (line 115) +* mpz_roinit_n: Integer Special Functions. + (line 67) +* MPZ_ROINIT_N: Integer Special Functions. + (line 83) +* mpz_root: Integer Roots. (line 6) +* mpz_rootrem: Integer Roots. (line 12) +* mpz_rrandomb: Integer Random Numbers. + (line 29) +* mpz_scan0: Integer Logic and Bit Fiddling. + (line 35) +* mpz_scan1: Integer Logic and Bit Fiddling. + (line 37) +* mpz_set: Assigning Integers. (line 9) +* mpz_setbit: Integer Logic and Bit Fiddling. + (line 51) +* mpz_set_d: Assigning Integers. (line 12) +* mpz_set_f: Assigning Integers. (line 14) +* mpz_set_q: Assigning Integers. (line 13) +* mpz_set_si: Assigning Integers. (line 11) +* mpz_set_str: Assigning Integers. (line 20) +* mpz_set_ui: Assigning Integers. (line 10) +* mpz_sgn: Integer Comparisons. (line 27) +* mpz_size: Integer Special Functions. + (line 30) +* mpz_sizeinbase: Miscellaneous Integer Functions. + (line 22) +* mpz_si_kronecker: Number Theoretic Functions. + (line 102) +* mpz_sqrt: Integer Roots. (line 17) +* mpz_sqrtrem: Integer Roots. (line 20) +* mpz_srcptr: Nomenclature and Types. + (line 55) +* mpz_sub: Integer Arithmetic. (line 11) +* mpz_submul: Integer Arithmetic. (line 30) +* mpz_submul_ui: Integer Arithmetic. (line 32) +* mpz_sub_ui: Integer Arithmetic. (line 12) +* mpz_swap: Assigning Integers. (line 36) +* mpz_t: Nomenclature and Types. + (line 6) +* mpz_tdiv_q: Integer Division. (line 54) +* mpz_tdiv_qr: Integer Division. (line 56) +* mpz_tdiv_qr_ui: Integer Division. (line 63) +* mpz_tdiv_q_2exp: Integer Division. (line 68) +* mpz_tdiv_q_ui: Integer Division. (line 59) +* mpz_tdiv_r: Integer Division. (line 55) +* mpz_tdiv_r_2exp: Integer Division. (line 71) +* mpz_tdiv_r_ui: Integer Division. (line 61) +* mpz_tdiv_ui: Integer Division. (line 65) +* mpz_tstbit: Integer Logic and Bit Fiddling. + (line 60) +* mpz_ui_kronecker: Number Theoretic Functions. + (line 103) +* mpz_ui_pow_ui: Integer Exponentiation. + (line 31) +* mpz_ui_sub: Integer Arithmetic. (line 14) +* mpz_urandomb: Integer Random Numbers. + (line 12) +* mpz_urandomm: Integer Random Numbers. + (line 21) +* mpz_xor: Integer Logic and Bit Fiddling. + (line 16) +* mp_bitcnt_t: Nomenclature and Types. + (line 42) +* mp_bits_per_limb: Useful Macros and Constants. + (line 7) +* mp_exp_t: Nomenclature and Types. + (line 27) +* mp_get_memory_functions: Custom Allocation. (line 86) +* mp_limb_t: Nomenclature and Types. + (line 31) +* mp_set_memory_functions: Custom Allocation. (line 14) +* mp_size_t: Nomenclature and Types. + (line 37) +* operator"": C++ Interface Integers. + (line 29) +* operator"" <1>: C++ Interface Rationals. + (line 36) +* operator"" <2>: C++ Interface Floats. + (line 55) +* operator%: C++ Interface Integers. + (line 34) +* operator/: C++ Interface Integers. + (line 33) +* operator<<: C++ Formatted Output. + (line 10) +* operator<< <1>: C++ Formatted Output. + (line 19) +* operator<< <2>: C++ Formatted Output. + (line 32) +* operator>>: C++ Formatted Input. (line 10) +* operator>> <1>: C++ Formatted Input. (line 13) +* operator>> <2>: C++ Formatted Input. (line 24) +* operator>> <3>: C++ Interface Rationals. + (line 86) +* primorial: C++ Interface Integers. + (line 73) +* sgn: C++ Interface Integers. + (line 65) +* sgn <1>: C++ Interface Rationals. + (line 56) +* sgn <2>: C++ Interface Floats. + (line 106) +* sqrt: C++ Interface Integers. + (line 66) +* sqrt <1>: C++ Interface Floats. + (line 107) +* swap: C++ Interface Integers. + (line 78) +* swap <1>: C++ Interface Rationals. + (line 59) +* swap <2>: C++ Interface Floats. + (line 110) +* trunc: C++ Interface Floats. + (line 111) + diff --git a/gmp-6.3.0/doc/gmp.texi b/gmp-6.3.0/doc/gmp.texi new file mode 100644 index 0000000..973c7b8 --- /dev/null +++ b/gmp-6.3.0/doc/gmp.texi @@ -0,0 +1,11073 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename gmp.info +@documentencoding ISO-8859-1 +@include version.texi +@settitle GNU MP @value{VERSION} +@synindex tp fn +@iftex +@afourpaper +@end iftex +@comment %**end of header + +@copying +This manual describes how to install and use the GNU multiple precision +arithmetic library, version @value{VERSION}. + +Copyright 1991, 1993-2016, 2018-2020 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document under +the terms of the GNU Free Documentation License, Version 1.3 or any later +version published by the Free Software Foundation; with no Invariant Sections, +with the Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover +Texts being ``You have freedom to copy and modify this GNU Manual, like GNU +software''. A copy of the license is included in +@ref{GNU Free Documentation License}. +@end copying +@c Note the @ref above must be on one line, a line break in an @ref within +@c @copying will bomb in recent texinfo.tex (e.g. 2004-04-07.08 which comes +@c with texinfo 4.7), with messages about missing @endcsname. + + +@c Texinfo version 4.2 or up will be needed to process this file. +@c +@c The version number and edition number are taken from version.texi provided +@c by automake (note that it's regenerated only if you configure with +@c --enable-maintainer-mode). +@c +@c Notes discussing the present version number of GMP in relation to previous +@c ones (for instance in the "Compatibility" section) must be updated at +@c manually though. +@c +@c @cindex entries have been made for function categories and programming +@c topics. The "mpn" section is not included in this, because a beginner +@c looking for "GCD" or something is only going to be confused by pointers to +@c low level routines. +@c +@c @cindex entries are present for processors and systems when there's +@c particular notes concerning them, but not just for everything GMP +@c supports. +@c +@c Index entries for files use @code rather than @file, @samp or @option, +@c since the latter come out with quotes in TeX, which are nice in the text +@c but don't look so good in index columns. +@c +@c Tex: +@c +@c A suitable texinfo.tex is supplied, a newer one should work equally well. +@c +@c HTML: +@c +@c Nothing special is done for links to external manuals, they just come out +@c in the usual makeinfo style, e.g. "../libc/Locales.html". If you have +@c local copies of such manuals then this is a good thing, if not then you +@c may want to search-and-replace to some online source. +@c + +@dircategory GNU libraries +@direntry +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +@end direntry + +@c html +@documentdescription +How to install and use the GNU multiple precision arithmetic library, version @value{VERSION}. +@end documentdescription + +@c smallbook +@finalout +@setchapternewpage on + +@ifnottex +@node Top, Copying, (dir), (dir) +@top GNU MP +@end ifnottex + +@iftex +@titlepage +@title GNU MP +@subtitle The GNU Multiple Precision Arithmetic Library +@subtitle Edition @value{EDITION} +@subtitle @value{UPDATED} + +@author by Torbj@"orn Granlund and the GMP development team +@c @email{tg@@gmplib.org} + +@c Include the Distribution inside the titlepage so +@c that headings are turned off. + +@tex +\global\parindent=0pt +\global\parskip=8pt +\global\baselineskip=13pt +@end tex + +@page +@vskip 0pt plus 1filll +@end iftex + +@insertcopying +@ifnottex +@sp 1 +@end ifnottex + +@iftex +@end titlepage +@headings double +@end iftex + +@c Don't bother with contents for html, the menus seem adequate. +@ifnothtml +@contents +@end ifnothtml + +@menu +* Copying:: GMP Copying Conditions (LGPL). +* Introduction to GMP:: Brief introduction to GNU MP. +* Installing GMP:: How to configure and compile the GMP library. +* GMP Basics:: What every GMP user should know. +* Reporting Bugs:: How to usefully report bugs. +* Integer Functions:: Functions for arithmetic on signed integers. +* Rational Number Functions:: Functions for arithmetic on rational numbers. +* Floating-point Functions:: Functions for arithmetic on floats. +* Low-level Functions:: Fast functions for natural numbers. +* Random Number Functions:: Functions for generating random numbers. +* Formatted Output:: @code{printf} style output. +* Formatted Input:: @code{scanf} style input. +* C++ Class Interface:: Class wrappers around GMP types. +* Custom Allocation:: How to customize the internal allocation. +* Language Bindings:: Using GMP from other languages. +* Algorithms:: What happens behind the scenes. +* Internals:: How values are represented behind the scenes. + +* Contributors:: Who brings you this library? +* References:: Some useful papers and books to read. +* GNU Free Documentation License:: +* Concept Index:: +* Function Index:: +@end menu + + +@c @m{T,N} is $T$ in tex or @math{N} otherwise. Commas in N or T don't work, +@c but @C{} can be used instead. +@iftex +@macro m {T,N} +@tex$\T\$@end tex +@end macro +@end iftex +@ifnottex +@macro m {T,N} +@math{\N\} +@end macro +@end ifnottex + +@c @mm{T,N} is $T$ tex and html and @math{N} in info. Commas in N or T don't +@c work, but @C{} can be used instead. +@iftex +@macro mm {T,N} +@tex$\T\$@end tex +@end macro +@end iftex + +@ifhtml +@macro mm {T,N} +@math{\T\} +@end macro +@end ifhtml + +@ifinfo +@macro mm {T,N} +@math{\N\} +@end macro +@end ifinfo + + +@macro C {} +, +@end macro + +@c @ms{V,N} is $V_N$ in tex or just vn otherwise. This suits simple +@c subscripts like @ms{x,0}. +@iftex +@macro ms {V,N} +@tex$\V\_{\N\}$@end tex +@end macro +@end iftex +@ifnottex +@macro ms {V,N} +\V\\N\ +@end macro +@end ifnottex + +@c @nicode{S} is plain S in info, or @code{S} elsewhere. This can be used +@c when the quotes that @code{} gives in info aren't wanted, but the +@c fontification in tex or html is wanted. Doesn't work as @nicode{'\\0'} +@c though (gives two backslashes in tex). +@ifinfo +@macro nicode {S} +\S\ +@end macro +@end ifinfo +@ifnotinfo +@macro nicode {S} +@code{\S\} +@end macro +@end ifnotinfo + +@c @nisamp{S} is plain S in info, or @samp{S} elsewhere. This can be used +@c when the quotes that @samp{} gives in info aren't wanted, but the +@c fontification in tex or html is wanted. +@ifinfo +@macro nisamp {S} +\S\ +@end macro +@end ifinfo +@ifnotinfo +@macro nisamp {S} +@samp{\S\} +@end macro +@end ifnotinfo + +@c Usage: @GMPtimes{} +@c Give either \times or the word "times". +@tex +\gdef\GMPtimes{\times} +@end tex +@ifnottex +@macro GMPtimes +times +@end macro +@end ifnottex + +@c Usage: @GMPmultiply{} +@c Give * in info, or nothing in tex. +@tex +\gdef\GMPmultiply{} +@end tex +@ifnottex +@macro GMPmultiply +* +@end macro +@end ifnottex + +@c Usage: @GMPabs{x} +@c Give either |x| in tex, or abs(x) in info or html. +@tex +\gdef\GMPabs#1{|#1|} +@end tex +@ifnottex +@macro GMPabs {X} +@abs{}(\X\) +@end macro +@end ifnottex + +@c Usage: @GMPfloor{x} +@c Give either \lfloor x\rfloor in tex, or floor(x) in info or html. +@tex +\gdef\GMPfloor#1{\lfloor #1\rfloor} +@end tex +@ifnottex +@macro GMPfloor {X} +floor(\X\) +@end macro +@end ifnottex + +@c Usage: @GMPceil{x} +@c Give either \lceil x\rceil in tex, or ceil(x) in info or html. +@tex +\gdef\GMPceil#1{\lceil #1 \rceil} +@end tex +@ifnottex +@macro GMPceil {X} +ceil(\X\) +@end macro +@end ifnottex + +@c Math operators already available in tex, made available in info too. +@c For example @bmod{} can be used in both tex and info. +@ifnottex +@macro bmod +mod +@end macro +@macro gcd +gcd +@end macro +@macro ge +>= +@end macro +@macro le +<= +@end macro +@macro log +log +@end macro +@macro min +min +@end macro +@macro leftarrow +<- +@end macro +@macro rightarrow +-> +@end macro +@end ifnottex + +@c New math operators. +@c @abs{} can be used in both tex and info, or just \abs in tex. +@tex +\gdef\abs{\mathop{\rm abs}} +@end tex +@ifnottex +@macro abs +abs +@end macro +@end ifnottex + +@c @cross{} is a \times symbol in tex, or an "x" in info. In tex it works +@c inside or outside $ $. +@tex +\gdef\cross{\ifmmode\times\else$\times$\fi} +@end tex +@ifnottex +@macro cross +x +@end macro +@end ifnottex + +@c @times{} made available as a "*" in info and html (already works in tex). +@ifnottex +@macro times +* +@end macro +@end ifnottex + +@c Usage: @W{text} +@c Like @w{} but working in math mode too. +@tex +\gdef\W#1{\ifmmode{#1}\else\w{#1}\fi} +@end tex +@ifnottex +@macro W {S} +@w{\S\} +@end macro +@end ifnottex + +@c Usage: \GMPdisplay{text} +@c Put the given text in an @display style indent, but without turning off +@c paragraph reflow etc. +@tex +\gdef\GMPdisplay#1{% +\noindent +\advance\leftskip by \lispnarrowing +#1\par} +@end tex + +@c Usage: \GMPhat +@c A new \hat that will work in math mode, unlike the texinfo redefined +@c version. +@tex +\gdef\GMPhat{\mathaccent"705E} +@end tex + +@c Usage: \GMPraise{text} +@c For use in a $ $ math expression as an alternative to "^". This is good +@c for @code{} in an exponent, since there seems to be no superscript font +@c for that. +@tex +\gdef\GMPraise#1{\mskip0.5\thinmuskip\hbox{\raise0.8ex\hbox{#1}}} +@end tex + +@c Usage: @texlinebreak{} +@c A line break as per @*, but only in tex. +@iftex +@macro texlinebreak +@* +@end macro +@end iftex +@ifnottex +@macro texlinebreak +@end macro +@end ifnottex + +@c Usage: @maybepagebreak +@c Allow tex to insert a page break, if it feels the urge. +@c Normally blocks of @deftypefun/funx are kept together, which can lead to +@c some poor page break positioning if it's a big block, like the sets of +@c division functions etc. +@tex +\gdef\maybepagebreak{\penalty0} +@end tex +@ifnottex +@macro maybepagebreak +@end macro +@end ifnottex + +@c Usage: @GMPreftop{info,title} +@c Usage: @GMPpxreftop{info,title} +@c +@c Like @ref{} and @pxref{}, but designed for a reference to the top of a +@c document, not a particular section. The TeX output for plain @ref insists +@c on printing a particular section, GMPreftop gives just the title. +@c +@c The texinfo manual recommends putting a likely section name in references +@c like this, e.g. "Introduction", but it seems better to just give the title. +@c +@iftex +@macro GMPreftop{info,title} +@i{\title\} +@end macro +@macro GMPpxreftop{info,title} +see @i{\title\} +@end macro +@end iftex +@c +@ifnottex +@macro GMPreftop{info,title} +@ref{Top,\title\,\title\,\info\,\title\} +@end macro +@macro GMPpxreftop{info,title} +@pxref{Top,\title\,\title\,\info\,\title\} +@end macro +@end ifnottex + + +@node Copying, Introduction to GMP, Top, Top +@comment node-name, next, previous, up +@unnumbered GNU MP Copying Conditions +@cindex Copying conditions +@cindex Conditions for copying GNU MP +@cindex License conditions + +This library is @dfn{free}; this means that everyone is free to use it and +free to redistribute it on a free basis. The library is not in the public +domain; it is copyrighted and there are restrictions on its distribution, but +these restrictions are designed to permit everything that a good cooperating +citizen would want to do. What is not allowed is to try to prevent others +from further sharing any version of this library that they might get from +you.@refill + +Specifically, we want to make sure that you have the right to give away copies +of the library, that you receive source code or else can get it if you want +it, that you can change this library or use pieces of it in new free programs, +and that you know you can do these things.@refill + +To make sure that everyone has such rights, we have to forbid you to deprive +anyone else of these rights. For example, if you distribute copies of the GNU +MP library, you must give the recipients all the rights that you have. You +must make sure that they, too, receive or can get the source code. And you +must tell them their rights.@refill + +Also, for our own protection, we must make certain that everyone finds out +that there is no warranty for the GNU MP library. If it is modified by +someone else and passed on, we want their recipients to know that what they +have is not what we distributed, so that any problems introduced by others +will not reflect on our reputation.@refill + +More precisely, the GNU MP library is dual licensed, under the conditions of +the GNU Lesser General Public License version 3 (see +@file{COPYING.LESSERv3}), or the GNU General Public License version 2 (see +@file{COPYINGv2}). This is the recipient's choice, and the recipient also has +the additional option of applying later versions of these licenses. (The +reason for this dual licensing is to make it possible to use the library with +programs which are licensed under GPL version 2, but which for historical or +other reasons do not allow use under later versions of the GPL.) + +Programs which are not part of the library itself, such as demonstration +programs and the GMP testsuite, are licensed under the terms of the GNU +General Public License version 3 (see @file{COPYINGv3}), or any later +version. + + +@node Introduction to GMP, Installing GMP, Copying, Top +@comment node-name, next, previous, up +@chapter Introduction to GNU MP +@cindex Introduction + +GNU MP is a portable library written in C for arbitrary precision arithmetic +on integers, rational numbers, and floating-point numbers. It aims to provide +the fastest possible arithmetic for all applications that need higher +precision than is directly supported by the basic C types. + +Many applications use just a few hundred bits of precision; but some +applications may need thousands or even millions of bits. GMP is designed to +give good performance for both, by choosing algorithms based on the sizes of +the operands, and by carefully keeping the overhead at a minimum. + +The speed of GMP is achieved by using fullwords as the basic arithmetic type, +by using sophisticated algorithms, by including carefully optimized assembly +code for the most common inner loops for many different CPUs, and by a general +emphasis on speed (as opposed to simplicity or elegance). + +There is assembly code for these CPUs: +@cindex CPU types +ARM Cortex-A9, Cortex-A15, and generic ARM, +DEC Alpha 21064, 21164, and 21264, +AMD K8 and K10 (sold under many brands, e.g. Athlon64, Phenom, Opteron), +Bulldozer, and Bobcat, +Intel Pentium, Pentium Pro/II/III, Pentium 4, Core2, Nehalem, Sandy bridge, Haswell, generic x86, +Intel IA-64, +Motorola/IBM PowerPC 32 and 64 such as POWER970, POWER5, POWER6, and POWER7, +MIPS 32-bit and 64-bit, +SPARC 32-bit and 64-bit with special support for all UltraSPARC models. +There is also assembly code for many obsolete CPUs. + + +@cindex Home page +@cindex Web page +@noindent +For up-to-date information on GMP, please see the GMP web pages at + +@display +@uref{https://gmplib.org/} +@end display + +@cindex Latest version of GMP +@cindex Anonymous FTP of latest version +@cindex FTP of latest version +@noindent +The latest version of the library is available at + +@display +@uref{https://ftp.gnu.org/gnu/gmp/} +@end display + +Many sites around the world mirror @samp{ftp.gnu.org}, please use a mirror +near you, see @uref{https://www.gnu.org/order/ftp.html} for a full list. + +@cindex Mailing lists +There are three public mailing lists of interest. One for release +announcements, one for general questions and discussions about usage of the GMP +library and one for bug reports. For more information, see + +@display +@uref{https://gmplib.org/mailman/listinfo/}. +@end display + +The proper place for bug reports is @email{gmp-bugs@@gmplib.org}. See +@ref{Reporting Bugs} for information about reporting bugs. + +@sp 1 +@section How to use this Manual +@cindex About this manual + +Everyone should read @ref{GMP Basics}. If you need to install the library +yourself, then read @ref{Installing GMP}. If you have a system with multiple +ABIs, then read @ref{ABI and ISA}, for the compiler options that must be used +on applications. + +The rest of the manual can be used for later reference, although it is +probably a good idea to glance through it. + + +@node Installing GMP, GMP Basics, Introduction to GMP, Top +@comment node-name, next, previous, up +@chapter Installing GMP +@cindex Installing GMP +@cindex Configuring GMP +@cindex Building GMP + +GMP has an autoconf/automake/libtool based configuration system. On a +Unix-like system a basic build can be done with + +@example +./configure +make +@end example + +@noindent +Some self-tests can be run with + +@example +make check +@end example + +@noindent +And you can install (under @file{/usr/local} by default) with + +@example +make install +@end example + +If you experience problems, please report them to @email{gmp-bugs@@gmplib.org}. +See @ref{Reporting Bugs}, for information on what to include in useful bug +reports. + +@menu +* Build Options:: +* ABI and ISA:: +* Notes for Package Builds:: +* Notes for Particular Systems:: +* Known Build Problems:: +* Performance optimization:: +@end menu + + +@node Build Options, ABI and ISA, Installing GMP, Installing GMP +@section Build Options +@cindex Build options + +All the usual autoconf configure options are available, run @samp{./configure +--help} for a summary. The file @file{INSTALL.autoconf} has some generic +installation information too. + +@table @asis +@item Tools +@cindex Non-Unix systems +@samp{configure} requires various Unix-like tools. See @ref{Notes for +Particular Systems}, for some options on non-Unix systems. + +It might be possible to build without the help of @samp{configure}, certainly +all the code is there, but unfortunately you'll be on your own. + +@item Build Directory +@cindex Build directory +To compile in a separate build directory, @command{cd} to that directory, and +prefix the configure command with the path to the GMP source directory. For +example + +@example +cd /my/build/dir +/my/sources/gmp-@value{VERSION}/configure +@end example + +Not all @samp{make} programs have the necessary features (@code{VPATH}) to +support this. In particular, SunOS and Slowaris @command{make} have bugs that +make them unable to build in a separate directory. Use GNU @command{make} +instead. + +@item @option{--prefix} and @option{--exec-prefix} +@cindex Prefix +@cindex Exec prefix +@cindex Install prefix +@cindex @code{--prefix} +@cindex @code{--exec-prefix} +The @option{--prefix} option can be used in the normal way to direct GMP to +install under a particular tree. The default is @samp{/usr/local}. + +@option{--exec-prefix} can be used to direct architecture-dependent files like +@file{libgmp.a} to a different location. This can be used to share +architecture-independent parts like the documentation, but separate the +dependent parts. Note however that @file{gmp.h} is +architecture-dependent since it encodes certain aspects of @file{libgmp}, so +it will be necessary to ensure both @file{$prefix/include} and +@file{$exec_prefix/include} are available to the compiler. + +@item @option{--disable-shared}, @option{--disable-static} +@cindex @code{--disable-shared} +@cindex @code{--disable-static} +By default both shared and static libraries are built (where possible), but +one or other can be disabled. Shared libraries result in smaller executables +and permit code sharing between separate running processes, but on some CPUs +are slightly slower, having a small cost on each function call. + +@item Native Compilation, @option{--build=CPU-VENDOR-OS} +@cindex Native compilation +@cindex Build system +@cindex @code{--build} +For normal native compilation, the system can be specified with +@samp{--build}. By default @samp{./configure} uses the output from running +@samp{./config.guess}. On some systems @samp{./config.guess} can determine +the exact CPU type, on others it will be necessary to give it explicitly. For +example, + +@example +./configure --build=ultrasparc-sun-solaris2.7 +@end example + +In all cases the @samp{OS} part is important, since it controls how libtool +generates shared libraries. Running @samp{./config.guess} is the simplest way +to see what it should be, if you don't know already. + +@item Cross Compilation, @option{--host=CPU-VENDOR-OS} +@cindex Cross compiling +@cindex Host system +@cindex @code{--host} +When cross-compiling, the system used for compiling is given by @samp{--build} +and the system where the library will run is given by @samp{--host}. For +example when using a FreeBSD Athlon system to build GNU/Linux m68k binaries, + +@example +./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu +@end example + +Compiler tools are sought first with the host system type as a prefix. For +example @command{m68k-mac-linux-gnu-ranlib} is tried, then plain +@command{ranlib}. This makes it possible for a set of cross-compiling tools +to co-exist with native tools. The prefix is the argument to @samp{--host}, +and this can be an alias, such as @samp{m68k-linux}. But note that tools +don't have to be set up this way, it's enough to just have a @env{PATH} with a +suitable cross-compiling @command{cc} etc. + +Compiling for a different CPU in the same family as the build system is a form +of cross-compilation, though very possibly this would merely be special +options on a native compiler. In any case @samp{./configure} avoids depending +on being able to run code on the build system, which is important when +creating binaries for a newer CPU since they very possibly won't run on the +build system. + +In all cases the compiler must be able to produce an executable (of whatever +format) from a standard C @code{main}. Although only object files will go to +make up @file{libgmp}, @samp{./configure} uses linking tests for various +purposes, such as determining what functions are available on the host system. + +Currently a warning is given unless an explicit @samp{--build} is used when +cross-compiling, because it may not be possible to correctly guess the build +system type if the @env{PATH} has only a cross-compiling @command{cc}. + +Note that the @samp{--target} option is not appropriate for GMP@. It's for use +when building compiler tools, with @samp{--host} being where they will run, +and @samp{--target} what they'll produce code for. Ordinary programs or +libraries like GMP are only interested in the @samp{--host} part, being where +they'll run. (Some past versions of GMP used @samp{--target} incorrectly.) + +@item CPU types +@cindex CPU types +In general, if you want a library that runs as fast as possible, you should +configure GMP for the exact CPU type your system uses. However, this may mean +the binaries won't run on older members of the family, and might run slower on +other members, older or newer. The best idea is always to build GMP for the +exact machine type you intend to run it on. + +The following CPUs have specific support. See @file{configure.ac} for details +of what code and compiler options they select. + +@itemize @bullet + +@c Keep this formatting, it's easy to read and it can be grepped to +@c automatically test that CPUs listed get through ./config.sub + +@item +Alpha: +@nisamp{alpha}, +@nisamp{alphaev5}, +@nisamp{alphaev56}, +@nisamp{alphapca56}, +@nisamp{alphapca57}, +@nisamp{alphaev6}, +@nisamp{alphaev67}, +@nisamp{alphaev68}, +@nisamp{alphaev7} + +@item +Cray: +@nisamp{c90}, +@nisamp{j90}, +@nisamp{t90}, +@nisamp{sv1} + +@item +HPPA: +@nisamp{hppa1.0}, +@nisamp{hppa1.1}, +@nisamp{hppa2.0}, +@nisamp{hppa2.0n}, +@nisamp{hppa2.0w}, +@nisamp{hppa64} + +@item +IA-64: +@nisamp{ia64}, +@nisamp{itanium}, +@nisamp{itanium2} + +@item +MIPS: +@nisamp{mips}, +@nisamp{mips3}, +@nisamp{mips64} + +@item +Motorola: +@nisamp{m68k}, +@nisamp{m68000}, +@nisamp{m68010}, +@nisamp{m68020}, +@nisamp{m68030}, +@nisamp{m68040}, +@nisamp{m68060}, +@nisamp{m68302}, +@nisamp{m68360}, +@nisamp{m88k}, +@nisamp{m88110} + +@item +POWER: +@nisamp{power}, +@nisamp{power1}, +@nisamp{power2}, +@nisamp{power2sc} + +@item +PowerPC: +@nisamp{powerpc}, +@nisamp{powerpc64}, +@nisamp{powerpc401}, +@nisamp{powerpc403}, +@nisamp{powerpc405}, +@nisamp{powerpc505}, +@nisamp{powerpc601}, +@nisamp{powerpc602}, +@nisamp{powerpc603}, +@nisamp{powerpc603e}, +@nisamp{powerpc604}, +@nisamp{powerpc604e}, +@nisamp{powerpc620}, +@nisamp{powerpc630}, +@nisamp{powerpc740}, +@nisamp{powerpc7400}, +@nisamp{powerpc7450}, +@nisamp{powerpc750}, +@nisamp{powerpc801}, +@nisamp{powerpc821}, +@nisamp{powerpc823}, +@nisamp{powerpc860}, +@nisamp{powerpc970} + +@item +SPARC: +@nisamp{sparc}, +@nisamp{sparcv8}, +@nisamp{microsparc}, +@nisamp{supersparc}, +@nisamp{sparcv9}, +@nisamp{ultrasparc}, +@nisamp{ultrasparc2}, +@nisamp{ultrasparc2i}, +@nisamp{ultrasparc3}, +@nisamp{sparc64} + +@item +x86 family: +@nisamp{i386}, +@nisamp{i486}, +@nisamp{i586}, +@nisamp{pentium}, +@nisamp{pentiummmx}, +@nisamp{pentiumpro}, +@nisamp{pentium2}, +@nisamp{pentium3}, +@nisamp{pentium4}, +@nisamp{k6}, +@nisamp{k62}, +@nisamp{k63}, +@nisamp{athlon}, +@nisamp{amd64}, +@nisamp{viac3}, +@nisamp{viac32} + +@item +Other: +@nisamp{arm}, +@nisamp{sh}, +@nisamp{sh2}, +@nisamp{vax}, +@end itemize + +CPUs not listed will use generic C code. + +@item Generic C Build +@cindex Generic C +If some of the assembly code causes problems, or if otherwise desired, the +generic C code can be selected with the configure @option{--disable-assembly}. + +Note that this will run quite slowly, but it should be portable and should at +least make it possible to get something running if all else fails. + +@item Fat binary, @option{--enable-fat} +@cindex Fat binary +@cindex @code{--enable-fat} +Using @option{--enable-fat} selects a ``fat binary'' build on x86, where +optimized low level subroutines are chosen at runtime according to the CPU +detected. This means more code, but gives good performance on all x86 chips. +(This option might become available for more architectures in the future.) + +@item @option{ABI} +@cindex ABI +On some systems GMP supports multiple ABIs (application binary interfaces), +meaning data type sizes and calling conventions. By default GMP chooses the +best ABI available, but a particular ABI can be selected. For example + +@example +./configure --host=mips64-sgi-irix6 ABI=n32 +@end example + +See @ref{ABI and ISA}, for the available choices on relevant CPUs, and what +applications need to do. + +@item @option{CC}, @option{CFLAGS} +@cindex C compiler +@cindex @code{CC} +@cindex @code{CFLAGS} +By default the C compiler used is chosen from among some likely candidates, +with @command{gcc} normally preferred if it's present. The usual +@samp{CC=whatever} can be passed to @samp{./configure} to choose something +different. + +For various systems, default compiler flags are set based on the CPU and +compiler. The usual @samp{CFLAGS="-whatever"} can be passed to +@samp{./configure} to use something different or to set good flags for systems +GMP doesn't otherwise know. + +The @samp{CC} and @samp{CFLAGS} used are printed during @samp{./configure}, +and can be found in each generated @file{Makefile}. This is the easiest way +to check the defaults when considering changing or adding something. + +Note that when @samp{CC} and @samp{CFLAGS} are specified on a system +supporting multiple ABIs it's important to give an explicit +@samp{ABI=whatever}, since GMP can't determine the ABI just from the flags and +won't be able to select the correct assembly code. + +If just @samp{CC} is selected then normal default @samp{CFLAGS} for that +compiler will be used (if GMP recognises it). For example @samp{CC=gcc} can +be used to force the use of GCC, with default flags (and default ABI). + +@item @option{CPPFLAGS} +@cindex @code{CPPFLAGS} +Any flags like @samp{-D} defines or @samp{-I} includes required by the +preprocessor should be set in @samp{CPPFLAGS} rather than @samp{CFLAGS}. +Compiling is done with both @samp{CPPFLAGS} and @samp{CFLAGS}, but +preprocessing uses just @samp{CPPFLAGS}. This distinction is because most +preprocessors won't accept all the flags the compiler does. Preprocessing is +done separately in some configure tests. + +@item @option{CC_FOR_BUILD} +@cindex @code{CC_FOR_BUILD} +Some build-time programs are compiled and run to generate host-specific data +tables. @samp{CC_FOR_BUILD} is the compiler used for this. It doesn't need +to be in any particular ABI or mode, it merely needs to generate executables +that can run. The default is to try the selected @samp{CC} and some likely +candidates such as @samp{cc} and @samp{gcc}, looking for something that works. + +No flags are used with @samp{CC_FOR_BUILD} because a simple invocation like +@samp{cc foo.c} should be enough. If some particular options are required +they can be included as for instance @samp{CC_FOR_BUILD="cc -whatever"}. + +@item C++ Support, @option{--enable-cxx} +@cindex C++ support +@cindex @code{--enable-cxx} +C++ support in GMP can be enabled with @samp{--enable-cxx}, in which case a +C++ compiler will be required. As a convenience @samp{--enable-cxx=detect} +can be used to enable C++ support only if a compiler can be found. The C++ +support consists of a library @file{libgmpxx.la} and header file +@file{gmpxx.h} (@pxref{Headers and Libraries}). + +A separate @file{libgmpxx.la} has been adopted rather than having C++ objects +within @file{libgmp.la} in order to ensure dynamic linked C programs aren't +bloated by a dependency on the C++ standard library, and to avoid any chance +that the C++ compiler could be required when linking plain C programs. + +@file{libgmpxx.la} will use certain internals from @file{libgmp.la} and can +only be expected to work with @file{libgmp.la} from the same GMP version. +Future changes to the relevant internals will be accompanied by renaming, so a +mismatch will cause unresolved symbols rather than perhaps mysterious +misbehaviour. + +In general @file{libgmpxx.la} will be usable only with the C++ compiler that +built it, since name mangling and runtime support are usually incompatible +between different compilers. + +@item @option{CXX}, @option{CXXFLAGS} +@cindex C++ compiler +@cindex @code{CXX} +@cindex @code{CXXFLAGS} +When C++ support is enabled, the C++ compiler and its flags can be set with +variables @samp{CXX} and @samp{CXXFLAGS} in the usual way. The default for +@samp{CXX} is the first compiler that works from a list of likely candidates, +with @command{g++} normally preferred when available. The default for +@samp{CXXFLAGS} is to try @samp{CFLAGS}, @samp{CFLAGS} without @samp{-g}, then +for @command{g++} either @samp{-g -O2} or @samp{-O2}, or for other compilers +@samp{-g} or nothing. Trying @samp{CFLAGS} this way is convenient when using +@samp{gcc} and @samp{g++} together, since the flags for @samp{gcc} will +usually suit @samp{g++}. + +It's important that the C and C++ compilers match, meaning their startup and +runtime support routines are compatible and that they generate code in the +same ABI (if there's a choice of ABIs on the system). @samp{./configure} +isn't currently able to check these things very well itself, so for that +reason @samp{--disable-cxx} is the default, to avoid a build failure due to a +compiler mismatch. Perhaps this will change in the future. + +Incidentally, it's normally not good enough to set @samp{CXX} to the same as +@samp{CC}. Although @command{gcc} for instance recognises @file{foo.cc} as +C++ code, only @command{g++} will invoke the linker the right way when +building an executable or shared library from C++ object files. + +@item Temporary Memory, @option{--enable-alloca=} +@cindex Temporary memory +@cindex Stack overflow +@cindex @code{alloca} +@cindex @code{--enable-alloca} +GMP allocates temporary workspace using one of the following three methods, +which can be selected with for instance +@samp{--enable-alloca=malloc-reentrant}. + +@itemize @bullet +@item +@samp{alloca} - C library or compiler builtin. +@item +@samp{malloc-reentrant} - the heap, in a re-entrant fashion. +@item +@samp{malloc-notreentrant} - the heap, with global variables. +@end itemize + +For convenience, the following choices are also available. +@samp{--disable-alloca} is the same as @samp{no}. + +@itemize @bullet +@item +@samp{yes} - a synonym for @samp{alloca}. +@item +@samp{no} - a synonym for @samp{malloc-reentrant}. +@item +@samp{reentrant} - @code{alloca} if available, otherwise +@samp{malloc-reentrant}. This is the default. +@item +@samp{notreentrant} - @code{alloca} if available, otherwise +@samp{malloc-notreentrant}. +@end itemize + +@code{alloca} is reentrant and fast, and is recommended. It actually allocates +just small blocks on the stack; larger ones use malloc-reentrant. + +@samp{malloc-reentrant} is, as the name suggests, reentrant and thread safe, +but @samp{malloc-notreentrant} is faster and should be used if reentrancy is +not required. + +The two malloc methods in fact use the memory allocation functions selected by +@code{mp_set_memory_functions}, these being @code{malloc} and friends by +default. @xref{Custom Allocation}. + +An additional choice @samp{--enable-alloca=debug} is available, to help when +debugging memory related problems (@pxref{Debugging}). + +@item FFT Multiplication, @option{--disable-fft} +@cindex FFT multiplication +@cindex @code{--disable-fft} +By default multiplications are done using Karatsuba, 3-way Toom, higher degree +Toom, and Fermat FFT@. The FFT is only used on large to very large operands +and can be disabled to save code size if desired. + +@item Assertion Checking, @option{--enable-assert} +@cindex Assertion checking +@cindex @code{--enable-assert} +This option enables some consistency checking within the library. This can be +of use while debugging, @pxref{Debugging}. + +@item Execution Profiling, @option{--enable-profiling=prof/gprof/instrument} +@cindex Execution profiling +@cindex @code{--enable-profiling} +Enable profiling support, in one of various styles, @pxref{Profiling}. + +@item @option{MPN_PATH} +@cindex @code{MPN_PATH} +Various assembly versions of each mpn subroutines are provided. For a given +CPU, a search is made through a path to choose a version of each. For example +@samp{sparcv8} has + +@example +MPN_PATH="sparc32/v8 sparc32 generic" +@end example + +which means look first for v8 code, then plain sparc32 (which is v7), and +finally fall back on generic C@. Knowledgeable users with special requirements +can specify a different path. Normally this is completely unnecessary. + +@item Documentation +@cindex Documentation formats +@cindex Texinfo +The source for the document you're now reading is @file{doc/gmp.texi}, in +Texinfo format, see @GMPreftop{texinfo, Texinfo}. + +@cindex Postscript +@cindex DVI +@cindex PDF +Info format @samp{doc/gmp.info} is included in the distribution. The usual +automake targets are available to make PostScript, DVI, PDF and HTML (these +will require various @TeX{} and Texinfo tools). + +@cindex DocBook +@cindex XML +DocBook and XML can be generated by the Texinfo @command{makeinfo} program +too, see @ref{makeinfo options,, Options for @command{makeinfo}, texinfo, +Texinfo}. + +Some supplementary notes can also be found in the @file{doc} subdirectory. + +@end table + + +@need 2000 +@node ABI and ISA, Notes for Package Builds, Build Options, Installing GMP +@section ABI and ISA +@cindex ABI +@cindex Application Binary Interface +@cindex ISA +@cindex Instruction Set Architecture + +ABI (Application Binary Interface) refers to the calling conventions between +functions, meaning what registers are used and what sizes the various C data +types are. ISA (Instruction Set Architecture) refers to the instructions and +registers a CPU has available. + +Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI defined, the +latter for compatibility with older CPUs in the family. GMP supports some +CPUs like this in both ABIs. In fact within GMP @samp{ABI} means a +combination of chip ABI, plus how GMP chooses to use it. For example in some +32-bit ABIs, GMP may support a limb as either a 32-bit @code{long} or a 64-bit +@code{long long}. + +By default GMP chooses the best ABI available for a given system, and this +generally gives significantly greater speed. But an ABI can be chosen +explicitly to make GMP compatible with other libraries, or particular +application requirements. For example, + +@example +./configure ABI=32 +@end example + +In all cases it's vital that all object code used in a given program is +compiled for the same ABI. + +Usually a limb is implemented as a @code{long}. When a @code{long long} limb +is used this is encoded in the generated @file{gmp.h}. This is convenient for +applications, but it does mean that @file{gmp.h} will vary, and can't be just +copied around. @file{gmp.h} remains compiler independent though, since all +compilers for a particular ABI will be expected to use the same limb type. + +Currently no attempt is made to follow whatever conventions a system has for +installing library or header files built for a particular ABI@. This will +probably only matter when installing multiple builds of GMP, and it might be +as simple as configuring with a special @samp{libdir}, or it might require +more than that. Note that builds for different ABIs need to be done separately, +with a fresh @command{./configure} and @command{make} each. + +@sp 1 +@table @asis +@need 1000 +@item AMD64 (@samp{x86_64}) +@cindex AMD64 +On AMD64 systems supporting both 32-bit and 64-bit modes for applications, the +following ABI choices are available. + +@table @asis +@item @samp{ABI=64} +The 64-bit ABI uses 64-bit limbs and pointers and makes full use of the chip +architecture. This is the default. Applications will usually not need +special compiler flags, but for reference the option is + +@example +gcc -m64 +@end example + +@item @samp{ABI=32} +The 32-bit ABI is the usual i386 conventions. This will be slower, and is not +recommended except for inter-operating with other code not yet 64-bit capable. +Applications must be compiled with + +@example +gcc -m32 +@end example + +(In GCC 2.95 and earlier there's no @samp{-m32} option, it's the only mode.) + +@item @samp{ABI=x32} +The x32 ABI uses 64-bit limbs but 32-bit pointers. Like the 64-bit ABI, it +makes full use of the chip's arithmetic capabilities. This ABI is not +supported by all operating systems. + +@example +gcc -mx32 +@end example + +@end table + +@sp 1 +@need 1000 +@item HPPA 2.0 (@samp{hppa2.0*}, @samp{hppa64}) +@cindex HPPA +@cindex HP-UX +@table @asis +@item @samp{ABI=2.0w} +The 2.0w ABI uses 64-bit limbs and pointers and is available on HP-UX 11 or +up. Applications must be compiled with + +@example +gcc [built for 2.0w] +cc +DD64 +@end example + +@item @samp{ABI=2.0n} +The 2.0n ABI means the 32-bit HPPA 1.0 ABI and all its normal calling +conventions, but with 64-bit instructions permitted within functions. GMP +uses a 64-bit @code{long long} for a limb. This ABI is available on hppa64 +GNU/Linux and on HP-UX 10 or higher. Applications must be compiled with + +@example +gcc [built for 2.0n] +cc +DA2.0 +e +@end example + +Note that current versions of GCC (e.g.@: 3.2) don't generate 64-bit +instructions for @code{long long} operations and so may be slower than for +2.0w. (The GMP assembly code is the same though.) + +@item @samp{ABI=1.0} +HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit HPPA 1.0 ABI@. +No special compiler options are needed for applications. +@end table + +All three ABIs are available for CPU types @samp{hppa2.0w}, @samp{hppa2.0} and +@samp{hppa64}, but for CPU type @samp{hppa2.0n} only 2.0n or 1.0 are +considered. + +Note that GCC on HP-UX has no options to choose between 2.0n and 2.0w modes, +unlike HP @command{cc}. Instead it must be built for one or the other ABI@. +GMP will detect how it was built, and skip to the corresponding @samp{ABI}. + +@sp 1 +@need 1500 +@item IA-64 under HP-UX (@samp{ia64*-*-hpux*}, @samp{itanium*-*-hpux*}) +@cindex IA-64 +@cindex HP-UX +HP-UX supports two ABIs for IA-64. GMP performance is the same in both. + +@table @asis +@item @samp{ABI=32} +In the 32-bit ABI, pointers, @code{int}s and @code{long}s are 32 bits and GMP +uses a 64 bit @code{long long} for a limb. Applications can be compiled +without any special flags since this ABI is the default in both HP C and GCC, +but for reference the flags are + +@example +gcc -milp32 +cc +DD32 +@end example + +@item @samp{ABI=64} +In the 64-bit ABI, @code{long}s and pointers are 64 bits and GMP uses a +@code{long} for a limb. Applications must be compiled with + +@example +gcc -mlp64 +cc +DD64 +@end example +@end table + +On other IA-64 systems, GNU/Linux for instance, @samp{ABI=64} is the only +choice. + +@sp 1 +@need 1000 +@item MIPS under IRIX 6 (@samp{mips*-*-irix[6789]}) +@cindex MIPS +@cindex IRIX +IRIX 6 always has a 64-bit MIPS 3 or better CPU, and supports ABIs o32, n32, +and 64. n32 or 64 are recommended, and GMP performance will be the same in +each. The default is n32. + +@table @asis +@item @samp{ABI=o32} +The o32 ABI is 32-bit pointers and integers, and no 64-bit operations. GMP +will be slower than in n32 or 64, this option only exists to support old +compilers, e.g.@: GCC 2.7.2. Applications can be compiled with no special +flags on an old compiler, or on a newer compiler with + +@example +gcc -mabi=32 +cc -32 +@end example + +@item @samp{ABI=n32} +The n32 ABI is 32-bit pointers and integers, but with a 64-bit limb using a +@code{long long}. Applications must be compiled with + +@example +gcc -mabi=n32 +cc -n32 +@end example + +@item @samp{ABI=64} +The 64-bit ABI is 64-bit pointers and integers. Applications must be compiled +with + +@example +gcc -mabi=64 +cc -64 +@end example +@end table + +Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have the necessary +support for n32 or 64 and so only gets a 32-bit limb and the MIPS 2 code. + +@sp 1 +@need 1000 +@item PowerPC 64 (@samp{powerpc64}, @samp{powerpc620}, @samp{powerpc630}, @samp{powerpc970}, @samp{power4}, @samp{power5}) +@cindex PowerPC +@table @asis +@item @samp{ABI=mode64} +@cindex AIX +The AIX 64 ABI uses 64-bit limbs and pointers and is the default on PowerPC 64 +@samp{*-*-aix*} systems. Applications must be compiled with + +@example +gcc -maix64 +xlc -q64 +@end example + +On 64-bit GNU/Linux, BSD, and Mac OS X/Darwin systems, the applications must +be compiled with + +@example +gcc -m64 +@end example + +@item @samp{ABI=mode32} +The @samp{mode32} ABI uses a 64-bit @code{long long} limb but with the chip +still in 32-bit mode and using 32-bit calling conventions. This is the default +for systems where the true 64-bit ABI is unavailable. No special compiler +options are typically needed for applications. This ABI is not available under +AIX. + +@item @samp{ABI=32} +This is the basic 32-bit PowerPC ABI, with a 32-bit limb. No special compiler +options are needed for applications. +@end table + +GMP's speed is greatest for the @samp{mode64} ABI, the @samp{mode32} ABI is 2nd +best. In @samp{ABI=32} only the 32-bit ISA is used and this doesn't make full +use of a 64-bit chip. + +@sp 1 +@need 1000 +@item Sparc V9 (@samp{sparc64}, @samp{sparcv9}, @samp{ultrasparc*}) +@cindex Sparc V9 +@cindex Solaris +@cindex Sun +@table @asis +@item @samp{ABI=64} +The 64-bit V9 ABI is available on the various BSD sparc64 ports, recent +versions of Sparc64 GNU/Linux, and Solaris 2.7 and up (when the kernel is in +64-bit mode). GCC 3.2 or higher, or Sun @command{cc} is required. On +GNU/Linux, depending on the default @command{gcc} mode, applications must be +compiled with + +@example +gcc -m64 +@end example + +On Solaris applications must be compiled with + +@example +gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 +cc -xarch=v9 +@end example + +On the BSD sparc64 systems no special options are required, since 64-bits is +the only ABI available. + +@item @samp{ABI=32} +For the basic 32-bit ABI, GMP still uses as much of the V9 ISA as it can. In +the Sun documentation this combination is known as ``v8plus''. On GNU/Linux, +depending on the default @command{gcc} mode, applications may need to be +compiled with + +@example +gcc -m32 +@end example + +On Solaris, no special compiler options are required for applications, though +using something like the following is recommended. (@command{gcc} 2.8 and +earlier only support @samp{-mv8} though.) + +@example +gcc -mv8plus +cc -xarch=v8plus +@end example +@end table + +GMP speed is greatest in @samp{ABI=64}, so it's the default where available. +The speed is partly because there are extra registers available and partly +because 64-bits is considered the more important case and has therefore had +better code written for it. + +Don't be confused by the names of the @samp{-m} and @samp{-x} compiler +options, they're called @samp{arch} but effectively control both ABI and ISA@. + +On Solaris 2.6 and earlier, only @samp{ABI=32} is available since the kernel +doesn't save all registers. + +On Solaris 2.7 with the kernel in 32-bit mode, a normal native build will +reject @samp{ABI=64} because the resulting executables won't run. +@samp{ABI=64} can still be built if desired by making it look like a +cross-compile, for example + +@example +./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64 +@end example +@end table + + +@need 2000 +@node Notes for Package Builds, Notes for Particular Systems, ABI and ISA, Installing GMP +@section Notes for Package Builds +@cindex Build notes for binary packaging +@cindex Packaged builds + +GMP should present no great difficulties for packaging in a binary +distribution. + +@cindex Libtool versioning +@cindex Shared library versioning +Libtool is used to build the library and @samp{-version-info} is set +appropriately, having started from @samp{3:0:0} in GMP 3.0 (@pxref{Versioning, +Library interface versions, Library interface versions, libtool, GNU +Libtool}). + +The GMP 4 series will be upwardly binary compatible in each release and will +be upwardly binary compatible with all of the GMP 3 series. Additional +function interfaces may be added in each release, so on systems where libtool +versioning is not fully checked by the loader an auxiliary mechanism may be +needed to express that a dynamic linked application depends on a new enough +GMP. + +An auxiliary mechanism may also be needed to express that @file{libgmpxx.la} +(from @option{--enable-cxx}, @pxref{Build Options}) requires @file{libgmp.la} +from the same GMP version, since this is not done by the libtool versioning, +nor otherwise. A mismatch will result in unresolved symbols from the linker, +or perhaps the loader. + +When building a package for a CPU family, care should be taken to use +@samp{--host} (or @samp{--build}) to choose the least common denominator among +the CPUs which might use the package. For example this might mean plain +@samp{sparc} (meaning V7) for SPARCs. + +For x86s, @option{--enable-fat} sets things up for a fat binary build, making a +runtime selection of optimized low level routines. This is a good choice for +packaging to run on a range of x86 chips. + +Users who care about speed will want GMP built for their exact CPU type, to +make best use of the available optimizations. Providing a way to suitably +rebuild a package may be useful. This could be as simple as making it +possible for a user to omit @samp{--build} (and @samp{--host}) so +@samp{./config.guess} will detect the CPU@. But a way to manually specify a +@samp{--build} will be wanted for systems where @samp{./config.guess} is +inexact. + +On systems with multiple ABIs, a packaged build will need to decide which +among the choices is to be provided, see @ref{ABI and ISA}. A given run of +@samp{./configure} etc will only build one ABI@. If a second ABI is also +required then a second run of @samp{./configure} etc must be made, starting +from a clean directory tree (@samp{make distclean}). + +As noted under ``ABI and ISA'', currently no attempt is made to follow system +conventions for install locations that vary with ABI, such as +@file{/usr/lib/sparcv9} for @samp{ABI=64} as opposed to @file{/usr/lib} for +@samp{ABI=32}. A package build can override @samp{libdir} and other standard +variables as necessary. + +Note that @file{gmp.h} is a generated file, and will be architecture and ABI +dependent. When attempting to install two ABIs simultaneously it will be +important that an application compile gets the correct @file{gmp.h} for its +desired ABI@. If compiler include paths don't vary with ABI options then it +might be necessary to create a @file{/usr/include/gmp.h} which tests +preprocessor symbols and chooses the correct actual @file{gmp.h}. + + +@need 2000 +@node Notes for Particular Systems, Known Build Problems, Notes for Package Builds, Installing GMP +@section Notes for Particular Systems +@cindex Build notes for particular systems +@cindex Particular systems +@cindex Systems +@table @asis + +@c This section is more or less meant for notes about performance or about +@c build problems that have been worked around but might leave a user +@c scratching their head. Fun with different ABIs on a system belongs in the +@c above section. + +@item AIX 3 and 4 +@cindex AIX +On systems @samp{*-*-aix[34]*} shared libraries are disabled by default, since +some versions of the native @command{ar} fail on the convenience libraries +used. A shared build can be attempted with + +@example +./configure --enable-shared --disable-static +@end example + +Note that the @samp{--disable-static} is necessary because in a shared build +libtool makes @file{libgmp.a} a symlink to @file{libgmp.so}, apparently for +the benefit of old versions of @command{ld} which only recognise @file{.a}, +but unfortunately this is done even if a fully functional @command{ld} is +available. + +@item ARM +@cindex ARM +On systems @samp{arm*-*-*}, versions of GCC up to and including 2.95.3 have a +bug in unsigned division, giving wrong results for some operands. GMP +@samp{./configure} will demand GCC 2.95.4 or later. + +@item Compaq C++ +@cindex Compaq C++ +Compaq C++ on OSF 5.1 has two flavours of @code{iostream}, a standard one and +an old pre-standard one (see @samp{man iostream_intro}). GMP can only use the +standard one, which unfortunately is not the default but must be selected by +defining @code{__USE_STD_IOSTREAM}. Configure with for instance + +@example +./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM +@end example + +@item Floating Point Mode +@cindex Floating point mode +@cindex Hardware floating point mode +@cindex Precision of hardware floating point +@cindex x87 +On some systems, the hardware floating point has a control mode which can set +all operations to be done in a particular precision, for instance single, +double or extended on x86 systems (x87 floating point). The GMP functions +involving a @code{double} cannot be expected to operate to their full +precision when the hardware is in single precision mode. Of course this +affects all code, including application code, not just GMP. + +@item FreeBSD 7.x, 8.x, 9.0, 9.1, 9.2 +@cindex FreeBSD +@command{m4} in these releases of FreeBSD has an eval function which ignores +its 2nd and 3rd arguments, which makes it unsuitable for @file{.asm} file +processing. @samp{./configure} will detect the problem and either abort or +choose another m4 in the @env{PATH}. The bug is fixed in FreeBSD 9.3 and 10.0, +so either upgrade or use GNU m4. Note that the FreeBSD package system installs +GNU m4 under the name @samp{gm4}, which GMP cannot guess. + +@item FreeBSD 7.x, 8.x, 9.x +@cindex FreeBSD +GMP releases starting with 6.0 do not support @samp{ABI=32} on FreeBSD/amd64 +prior to release 10.0 of the system. The cause is a broken @code{limits.h}, +which GMP no longer works around. + +@item MS-DOS and MS Windows +@cindex MS-DOS +@cindex MS Windows +@cindex Windows +@cindex Cygwin +@cindex DJGPP +@cindex MINGW +On an MS-DOS system DJGPP can be used to build GMP, and on an MS Windows +system Cygwin, DJGPP and MINGW can be used. All three are excellent ports of +GCC and the various GNU tools. + +@display +@uref{https://www.cygwin.com/} +@uref{http://www.delorie.com/djgpp/} +@uref{http://www.mingw.org/} +@end display + +@cindex Interix +@cindex Services for Unix +Microsoft also publishes an Interix ``Services for Unix'' which can be used to +build GMP on Windows (with a normal @samp{./configure}), but it's not free +software. + +@item MS Windows DLLs +@cindex DLLs +@cindex MS Windows +@cindex Windows +On systems @samp{*-*-cygwin*}, @samp{*-*-mingw*} and @samp{*-*-pw32*} by +default GMP builds only a static library, but a DLL can be built instead using + +@example +./configure --disable-static --enable-shared +@end example + +Static and DLL libraries can't both be built, since certain export directives +in @file{gmp.h} must be different. + +A MINGW DLL build of GMP can be used with Microsoft C@. Libtool doesn't +install a @file{.lib} format import library, but it can be created with MS +@command{lib} as follows, and copied to the install directory. Similarly for +@file{libmp} and @file{libgmpxx}. + +@example +cd .libs +lib /def:libgmp-3.dll.def /out:libgmp-3.lib +@end example + +MINGW uses the C runtime library @samp{msvcrt.dll} for I/O, so applications +wanting to use the GMP I/O routines must be compiled with @samp{cl /MD} to do +the same. If one of the other C runtime library choices provided by MS C is +desired then the suggestion is to use the GMP string functions and confine I/O +to the application. + +@item Motorola 68k CPU Types +@cindex 68000 +@samp{m68k} is taken to mean 68000. @samp{m68020} or higher will give a +performance boost on applicable CPUs. @samp{m68360} can be used for CPU32 +series chips. @samp{m68302} can be used for ``Dragonball'' series chips, +though this is merely a synonym for @samp{m68000}. + +@item NetBSD 5.x +@cindex NetBSD +@command{m4} in these releases of NetBSD has an eval function which ignores its +2nd and 3rd arguments, which makes it unsuitable for @file{.asm} file +processing. @samp{./configure} will detect the problem and either abort or +choose another m4 in the @env{PATH}. The bug is fixed in NetBSD 6, so either +upgrade or use GNU m4. Note that the NetBSD package system installs GNU m4 +under the name @samp{gm4}, which GMP cannot guess. + +@item OpenBSD 2.6 +@cindex OpenBSD +@command{m4} in this release of OpenBSD has a bug in @code{eval} that makes it +unsuitable for @file{.asm} file processing. @samp{./configure} will detect +the problem and either abort or choose another m4 in the @env{PATH}. The bug +is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. + +@item Power CPU Types +@cindex Power/PowerPC +In GMP, CPU types @samp{power*} and @samp{powerpc*} will each use instructions +not available on the other, so it's important to choose the right one for the +CPU that will be used. Currently GMP has no assembly code support for using +just the common instruction subset. To get executables that run on both, the +current suggestion is to use the generic C code (@option{--disable-assembly}), +possibly with appropriate compiler options (like @samp{-mcpu=common} for +@command{gcc}). CPU @samp{rs6000} (which is not a CPU but a family of +workstations) is accepted by @file{config.sub}, but is currently equivalent to +@option{--disable-assembly}. + +@item Sparc CPU Types +@cindex Sparc +@samp{sparcv8} or @samp{supersparc} on relevant systems will give a +significant performance increase over the V7 code selected by plain +@samp{sparc}. + +@item Sparc App Regs +@cindex Sparc +The GMP assembly code for both 32-bit and 64-bit Sparc clobbers the +``application registers'' @code{g2}, @code{g3} and @code{g4}, the same way +that the GCC default @samp{-mapp-regs} does (@pxref{SPARC Options,, SPARC +Options, gcc, Using the GNU Compiler Collection (GCC)}). + +This makes that code unsuitable for use with the special V9 +@samp{-mcmodel=embmedany} (which uses @code{g4} as a data segment pointer), and +for applications wanting to use those registers for special purposes. In these +cases the only suggestion currently is to build GMP with +@option{--disable-assembly} to avoid the assembly code. + +@item SunOS 4 +@cindex SunOS +@command{/usr/bin/m4} lacks various features needed to process @file{.asm} +files, and instead @samp{./configure} will automatically use +@command{/usr/5bin/m4}, which we believe is always available (if not then use +GNU m4). + +@item x86 CPU Types +@cindex x86 +@cindex 80x86 +@cindex i386 +@samp{i586}, @samp{pentium} or @samp{pentiummmx} code is good for its intended +P5 Pentium chips, but quite slow when run on Intel P6 class chips (PPro, P-II, +P-III)@. @samp{i386} is a better choice when making binaries that must run on +both. + +@item x86 MMX and SSE2 Code +@cindex MMX +@cindex SSE2 +If the CPU selected has MMX code but the assembler doesn't support it, a +warning is given and non-MMX code is used instead. This will be an inferior +build, since the MMX code that's present is there because it's faster than the +corresponding plain integer code. The same applies to SSE2. + +Old versions of @samp{gas} don't support MMX instructions, in particular +version 1.92.3 that comes with FreeBSD 2.2.8 or the more recent OpenBSD 3.1 +doesn't. + +Solaris 2.6 and 2.7 @command{as} generate incorrect object code for register +to register @code{movq} instructions, and so can't be used for MMX code. +Install a recent @command{gas} if MMX code is wanted on these systems. +@end table + + +@need 2000 +@node Known Build Problems, Performance optimization, Notes for Particular Systems, Installing GMP +@section Known Build Problems +@cindex Build problems known + +@c This section is more or less meant for known build problems that are not +@c otherwise worked around and require some sort of manual intervention. + +You might find more up-to-date information at @uref{https://gmplib.org/}. + +@table @asis +@item Compiler link options +The version of libtool currently in use rather aggressively strips compiler +options when linking a shared library. This will hopefully be relaxed in the +future, but for now if this is a problem the suggestion is to create a little +script to hide them, and for instance configure with + +@example +./configure CC=gcc-with-my-options +@end example + +@item DJGPP (@samp{*-*-msdosdjgpp*}) +@cindex DJGPP +The DJGPP port of @command{bash} 2.03 is unable to run the @samp{configure} +script, it exits silently, having died writing a preamble to +@file{config.log}. Use @command{bash} 2.04 or higher. + +@samp{make all} was found to run out of memory during the final +@file{libgmp.la} link on one system tested, despite having 64MiB available. +Running @samp{make libgmp.la} directly helped, perhaps recursing into the +various subdirectories uses up memory. + +@item GNU binutils @command{strip} prior to 2.12 +@cindex Stripped libraries +@cindex Binutils @command{strip} +@cindex GNU @command{strip} +@command{strip} from GNU binutils 2.11 and earlier should not be used on the +static libraries @file{libgmp.a} and @file{libmp.a} since it will discard all +but the last of multiple archive members with the same name, like the three +versions of @file{init.o} in @file{libgmp.a}. Binutils 2.12 or higher can be +used successfully. + +The shared libraries @file{libgmp.so} and @file{libmp.so} are not affected by +this and any version of @command{strip} can be used on them. + +@item @command{make} syntax error +@cindex SCO +@cindex IRIX +On certain versions of SCO OpenServer 5 and IRIX 6.5 the native @command{make} +is unable to handle the long dependencies list for @file{libgmp.la}. The +symptom is a ``syntax error'' on the following line of the top-level +@file{Makefile}. + +@example +libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES) +@end example + +Either use GNU Make, or as a workaround remove +@code{$(libgmp_la_DEPENDENCIES)} from that line (which will make the initial +build work, but if any recompiling is done @file{libgmp.la} might not be +rebuilt). + +@item MacOS X (@samp{*-*-darwin*}) +@cindex MacOS X +@cindex Darwin +Libtool currently only knows how to create shared libraries on MacOS X using +the native @command{cc} (which is a modified GCC), not a plain GCC@. A +static-only build should work though (@samp{--disable-shared}). + +@item NeXT prior to 3.3 +@cindex NeXT +The system compiler on old versions of NeXT was a massacred and old GCC, even +if it called itself @file{cc}. This compiler cannot be used to build GMP, you +need to get a real GCC, and install that. (NeXT may have fixed this in +release 3.3 of their system.) + +@item POWER and PowerPC +@cindex Power/PowerPC +Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP on POWER or +PowerPC@. If you want to use GCC for these machines, get GCC 2.7.2.1 (or +later). + +@item Sequent Symmetry +@cindex Sequent Symmetry +Use the GNU assembler instead of the system assembler, since the latter has +serious bugs. + +@item Solaris 2.6 +@cindex Solaris +The system @command{sed} prints an error ``Output line too long'' when libtool +builds @file{libgmp.la}. This doesn't seem to cause any obvious ill effects, +but GNU @command{sed} is recommended, to avoid any doubt. + +@item Sparc Solaris 2.7 with gcc 2.95.2 in @samp{ABI=32} +@cindex Solaris +A shared library build of GMP seems to fail in this combination, it builds but +then fails the tests, apparently due to some incorrect data relocations within +@code{gmp_randinit_lc_2exp_size}. The exact cause is unknown, +@samp{--disable-shared} is recommended. +@end table + + +@need 2000 +@node Performance optimization, , Known Build Problems, Installing GMP +@section Performance optimization +@cindex Optimizing performance + +@c At some point, this should perhaps move to a separate chapter on optimizing +@c performance. + +For optimal performance, build GMP for the exact CPU type of the target +computer, see @ref{Build Options}. + +Unlike what is the case for most other programs, the compiler typically +doesn't matter much, since GMP uses assembly language for the most critical +operation. + +In particular for long-running GMP applications, and applications demanding +extremely large numbers, building and running the @code{tuneup} program in the +@file{tune} subdirectory can be important. For example, + +@example +cd tune +make tuneup +./tuneup +@end example + +will generate better contents for the @file{gmp-mparam.h} parameter file. + +To use the results, put the output in the file indicated in the +@samp{Parameters for ...} header. Then recompile from scratch. + +The @code{tuneup} program takes one useful parameter, @samp{-f NNN}, which +instructs the program how long to check FFT multiply parameters. If you're +going to use GMP for extremely large numbers, you may want to run @code{tuneup} +with a large NNN value. + + +@node GMP Basics, Reporting Bugs, Installing GMP, Top +@comment node-name, next, previous, up +@chapter GMP Basics +@cindex Basics + +@strong{Using functions, macros, data types, etc.@: not documented in this +manual is strongly discouraged. If you do so your application is guaranteed +to be incompatible with future versions of GMP.} + +@menu +* Headers and Libraries:: +* Nomenclature and Types:: +* Function Classes:: +* Variable Conventions:: +* Parameter Conventions:: +* Memory Management:: +* Reentrancy:: +* Useful Macros and Constants:: +* Compatibility with older versions:: +* Demonstration Programs:: +* Efficiency:: +* Debugging:: +* Profiling:: +* Autoconf:: +* Emacs:: +@end menu + +@node Headers and Libraries, Nomenclature and Types, GMP Basics, GMP Basics +@section Headers and Libraries +@cindex Headers + +@cindex @file{gmp.h} +@cindex Include files +@cindex @code{#include} +All declarations needed to use GMP are collected in the include file +@file{gmp.h}, except for the @ref{C++ Class Interface} which comes with its +own separate header @file{gmpxx.h}. @file{gmp.h} is designed to work with +both C and C++ compilers. + +@example +#include +@end example + +@cindex @code{stdio.h} +Note however that prototypes for GMP functions with @code{FILE *} parameters +are only provided if @code{} is included before. + +@example +#include +#include +@end example + +@cindex @code{stdarg.h} +Likewise @code{} is required for prototypes with @code{va_list} +parameters, such as @code{gmp_vprintf}. And @code{} for prototypes +with @code{struct obstack} parameters, such as @code{gmp_obstack_printf}, when +available. + +@cindex Libraries +@cindex Linking +@cindex @code{libgmp} +All programs using GMP must link against the @file{libgmp} library. On a +typical Unix-like system this can be done with @samp{-lgmp}, for example + +@example +gcc myprogram.c -lgmp +@end example + +@cindex @code{libgmpxx} +GMP C++ functions are in a separate @file{libgmpxx} library, including the +@ref{C++ Class Interface} but also @ref{C++ Formatted Output} for regular +GMP types. This is built and installed if C++ support has been enabled +(@pxref{Build Options}). For example, + +@example +g++ mycxxprog.cc -lgmpxx -lgmp +@end example + +@cindex Libtool +GMP is built using Libtool and an application can use that to link if desired, +@GMPpxreftop{libtool, GNU Libtool}. + +If GMP has been installed to a non-standard location then it may be necessary +to use @samp{-I} and @samp{-L} compiler options to point to the right +directories, and some sort of run-time path for a shared library. + + +@node Nomenclature and Types, Function Classes, Headers and Libraries, GMP Basics +@section Nomenclature and Types +@cindex Nomenclature +@cindex Types + +@cindex Integer +@tindex @code{mpz_t} +In this manual, @dfn{integer} usually means a multiple precision integer, as +defined by the GMP library. The C data type for such integers is @code{mpz_t}. +Here are some examples of how to declare such integers: + +@example +mpz_t sum; + +struct foo @{ mpz_t x, y; @}; + +mpz_t vec[20]; +@end example + +@cindex Rational number +@tindex @code{mpq_t} +@dfn{Rational number} means a multiple precision fraction. The C data type +for these fractions is @code{mpq_t}. For example: + +@example +mpq_t quotient; +@end example + +@cindex Floating-point number +@tindex @code{mpf_t} +@dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision +mantissa with a limited precision exponent. The C data type for such objects +is @code{mpf_t}. For example: + +@example +mpf_t fp; +@end example + +@tindex @code{mp_exp_t} +The floating point functions accept and return exponents in the C type +@code{mp_exp_t}. Currently this is usually a @code{long}, but on some systems +it's an @code{int} for efficiency. + +@cindex Limb +@tindex @code{mp_limb_t} +A @dfn{limb} means the part of a multi-precision number that fits in a single +machine word. (We chose this word because a limb of the human body is +analogous to a digit, only larger, and containing several digits.) Normally a +limb is 32 or 64 bits. The C data type for a limb is @code{mp_limb_t}. + +@tindex @code{mp_size_t} +Counts of limbs of a multi-precision number represented in the C type +@code{mp_size_t}. Currently this is normally a @code{long}, but on some +systems it's an @code{int} for efficiency, and on some systems it will be +@code{long long} in the future. + +@tindex @code{mp_bitcnt_t} +Counts of bits of a multi-precision number are represented in the C type +@code{mp_bitcnt_t}. Currently this is always an @code{unsigned long}, but on +some systems it will be an @code{unsigned long long} in the future. + +@cindex Random state +@tindex @code{gmp_randstate_t} +@dfn{Random state} means an algorithm selection and current state data. The C +data type for such objects is @code{gmp_randstate_t}. For example: + +@example +gmp_randstate_t rstate; +@end example + +Also, in general @code{mp_bitcnt_t} is used for bit counts and ranges, and +@code{size_t} is used for byte or character counts. + +@sp 1 + +@cindex Pointer types +@tindex @code{mpz_ptr} +@tindex @code{mpz_srcptr} +@tindex @code{mpq_ptr} +@tindex @code{mpq_srcptr} +@tindex @code{mpf_ptr} +@tindex @code{mpf_srcptr} +@tindex @code{gmp_randstate_ptr} +@tindex @code{gmp_randstate_srcptr} +Internally, GMP data types such as @code{mpz_t} are defined as one-element +arrays, whose element type is part of the GMP internals (@pxref{Internals}). + +When an array is used as a function argument in C, it is not passed by value, +instead its value is a pointer to the first element. In C jargon, this is +sometimes referred to as the array "decaying" to a pointer. For GMP types like +@code{mpz_t}, that means that the function called gets a pointer to the +caller's @code{mpz_t} value, which is why no explicit @code{&} operator is +needed when passing output arguments (@pxref{Parameter Conventions}). + +GMP defines names for these pointer types, e.g., @code{mpz_ptr} corresponding +to @code{mpz_t}, and @code{mpz_srcptr} corresponding to @code{const mpz_t}. +Most functions don't need to use these pointer types directly; it works fine to +declare a function using the @code{mpz_t} or @code{const mpz_t} as the argument +types, the same "pointer decay" happens in the background regardless. + +Occasionally, it is useful to manipulate pointers directly, e.g., to +conditionally swap @emph{references} to a function's inputs without changing +the @emph{values} as seen by the caller, or returning a pointer to an +@code{mpz_t} which is part of a larger structure. For these cases, the pointer +types are necessary. And a @code{mpz_ptr} can be passed as argument to any GMP +function declared to take an @code{mpz_t} argument. + +Their definition is equivalent to the following code, which is given for +illustratory purposes only: + +@example + typedef foo_internal foo_t[1]; + typedef foo_internal * foo_ptr; + typedef const foo_internal * foo_srcptr; +@end example + +The following pointer types are defined by GMP: +@itemize +@item @code{mpz_ptr} for pointers to the element type in @code{mpz_t} +@item @code{mpz_srcptr} for @code{const} pointers to the element type in @code{mpz_t} +@item @code{mpq_ptr} for pointers to the element type in @code{mpq_t} +@item @code{mpq_srcptr} for @code{const} pointers to the element type in @code{mpq_t} +@item @code{mpf_ptr} for pointers to the element type in @code{mpf_t} +@item @code{mpf_srcptr} for @code{const} pointers to the element type in @code{mpf_t} +@item @code{gmp_randstate_ptr} for pointers to the element type in @code{gmp_randstate_t} +@item @code{gmp_randstate_srcptr} for @code{const} pointers to the element type in @code{gmp_randstate_t} +@end itemize + +@node Function Classes, Variable Conventions, Nomenclature and Types, GMP Basics +@section Function Classes +@cindex Function classes + +There are six classes of functions in the GMP library: + +@enumerate +@item +Functions for signed integer arithmetic, with names beginning with +@code{mpz_}. The associated type is @code{mpz_t}. There are about 150 +functions in this class. (@pxref{Integer Functions}) + +@item +Functions for rational number arithmetic, with names beginning with +@code{mpq_}. The associated type is @code{mpq_t}. There are about 35 +functions in this class, but the integer functions can be used for arithmetic +on the numerator and denominator separately. (@pxref{Rational Number +Functions}) + +@item +Functions for floating-point arithmetic, with names beginning with +@code{mpf_}. The associated type is @code{mpf_t}. There are about 70 +functions in this class. (@pxref{Floating-point Functions}) + +@item +Fast low-level functions that operate on natural numbers. These are used by +the functions in the preceding groups, and you can also call them directly +from very time-critical user programs. These functions' names begin with +@code{mpn_}. The associated type is array of @code{mp_limb_t}. There are +about 60 (hard-to-use) functions in this class. (@pxref{Low-level Functions}) + +@item +Miscellaneous functions. Functions for setting up custom allocation and +functions for generating random numbers. (@pxref{Custom Allocation}, and +@pxref{Random Number Functions}) +@end enumerate + + +@node Variable Conventions, Parameter Conventions, Function Classes, GMP Basics +@section Variable Conventions +@cindex Variable conventions +@cindex Conventions for variables + +GMP functions generally have output arguments before input arguments. This +notation is by analogy with the assignment operator. + +GMP lets you use the same variable for both input and output in one call. For +example, the main function for integer multiplication, @code{mpz_mul}, can be +used to square @code{x} and put the result back in @code{x} with + +@example +mpz_mul (x, x, x); +@end example + +Before you can assign to a GMP variable, you need to initialize it by calling +one of the special initialization functions. When you're done with a +variable, you need to clear it out, using one of the functions for that +purpose. Which function to use depends on the type of variable. See the +chapters on integer functions, rational number functions, and floating-point +functions for details. + +A variable should only be initialized once, or at least cleared between each +initialization. After a variable has been initialized, it may be assigned to +any number of times. + +For efficiency reasons, avoid excessive initializing and clearing. In +general, initialize near the start of a function and clear near the end. For +example, + +@example +void +foo (void) +@{ + mpz_t n; + int i; + mpz_init (n); + for (i = 1; i < 100; i++) + @{ + mpz_mul (n, @dots{}); + mpz_fdiv_q (n, @dots{}); + @dots{} + @} + mpz_clear (n); +@} +@end example + +GMP types like @code{mpz_t} are implemented as one-element arrays of certain +structures. Declaring a variable creates an object with the fields GMP needs, +but variables are normally manipulated by using the pointer to the +object. The appropriate pointer types (@ref{Nomenclature and Types}) may +be used to explicitly manipulate the pointer. For +both behavior and efficiency reasons, it is discouraged to make copies of the +GMP object itself (either directly or via aggregate objects containing such GMP +objects). If copies are done, all of them must be used read-only; using a copy +as the output of some function will invalidate all the other copies. Note that +the actual fields in each @code{mpz_t} etc are for internal use only and should +not be accessed directly by code that expects to be compatible with future GMP +releases. + +@node Parameter Conventions, Memory Management, Variable Conventions, GMP Basics +@section Parameter Conventions +@cindex Parameter conventions +@cindex Conventions for parameters + +When a GMP variable is used as a function parameter, it's effectively a +call-by-reference, meaning that when the function stores a value there it will +change the original in the caller. Parameters which are input-only can be +designated @code{const} to provoke a compiler error or warning on attempting to +modify them. + +When a function is going to return a GMP result, it should designate a +parameter that it sets, like the library functions do. More than one value +can be returned by having more than one output parameter, again like the +library functions. A @code{return} of an @code{mpz_t} etc doesn't return the +object, only a pointer, and this is almost certainly not what's wanted. + +Here's an example accepting an @code{mpz_t} parameter, doing a calculation, +and storing the result to the indicated parameter. + +@example +void +foo (mpz_t result, const mpz_t param, unsigned long n) +@{ + unsigned long i; + mpz_mul_ui (result, param, n); + for (i = 1; i < n; i++) + mpz_add_ui (result, result, i*7); +@} + +int +main (void) +@{ + mpz_t r, n; + mpz_init (r); + mpz_init_set_str (n, "123456", 0); + foo (r, n, 20L); + gmp_printf ("%Zd\n", r); + return 0; +@} +@end example + +Our function @code{foo} works even if its caller passes the same variable for +@code{param} and @code{result}, just like the library functions. But +sometimes it's tricky to make that work, and an application might not want to +bother supporting that sort of thing. + +Since GMP types are implemented as one-element arrays, using a GMP variable as +a parameter passes a pointer to the object. Hence the call-by-reference. +A more explicit (and equivalent) prototype for our function @code{foo} +could be: + +@example +void foo (mpz_ptr result, mpz_srcptr param, unsigned long n); +@end example + + + +@need 1000 +@node Memory Management, Reentrancy, Parameter Conventions, GMP Basics +@section Memory Management +@cindex Memory management + +The GMP types like @code{mpz_t} are small, containing only a couple of sizes, +and pointers to allocated data. Once a variable is initialized, GMP takes +care of all space allocation. Additional space is allocated whenever a +variable doesn't have enough. + +@code{mpz_t} and @code{mpq_t} variables never reduce their allocated space. +Normally this is the best policy, since it avoids frequent reallocation. +Applications that need to return memory to the heap at some particular point +can use @code{mpz_realloc2}, or clear variables no longer needed. + +@code{mpf_t} variables, in the current implementation, use a fixed amount of +space, determined by the chosen precision and allocated at initialization, so +their size doesn't change. + +All memory is allocated using @code{malloc} and friends by default, but this +can be changed, see @ref{Custom Allocation}. Temporary memory on the stack is +also used (via @code{alloca}), but this can be changed at build-time if +desired, see @ref{Build Options}. + + +@node Reentrancy, Useful Macros and Constants, Memory Management, GMP Basics +@section Reentrancy +@cindex Reentrancy +@cindex Thread safety +@cindex Multi-threading + +@noindent +GMP is reentrant and thread-safe, with some exceptions: + +@itemize @bullet +@item +If configured with @option{--enable-alloca=malloc-notreentrant} (or with +@option{--enable-alloca=notreentrant} when @code{alloca} is not available), +then naturally GMP is not reentrant. + +@item +@code{mpf_set_default_prec} and @code{mpf_init} use a global variable for the +selected precision. @code{mpf_init2} can be used instead, and in the C++ +interface an explicit precision to the @code{mpf_class} constructor. + +@item +@code{mpz_random} and the other old random number functions use a global +random state and are hence not reentrant. The newer random number functions +that accept a @code{gmp_randstate_t} parameter can be used instead. + +@item +@code{gmp_randinit} (obsolete) returns an error indication through a global +variable, which is not thread safe. Applications are advised to use +@code{gmp_randinit_default} or @code{gmp_randinit_lc_2exp} instead. + +@item +@code{mp_set_memory_functions} uses global variables to store the selected +memory allocation functions. + +@item +If the memory allocation functions set by a call to +@code{mp_set_memory_functions} (or @code{malloc} and friends by default) are +not reentrant, then GMP will not be reentrant either. + +@item +If the standard I/O functions such as @code{fwrite} are not reentrant then the +GMP I/O functions using them will not be reentrant either. + +@item +It's safe for two threads to read from the same GMP variable simultaneously, +but it's not safe for one to read while another might be writing, nor for +two threads to write simultaneously. It's not safe for two threads to +generate a random number from the same @code{gmp_randstate_t} simultaneously, +since this involves an update of that variable. +@end itemize + + +@need 2000 +@node Useful Macros and Constants, Compatibility with older versions, Reentrancy, GMP Basics +@section Useful Macros and Constants +@cindex Useful macros and constants +@cindex Constants + +@deftypevr {Global Constant} {const int} mp_bits_per_limb +@findex mp_bits_per_limb +@cindex Bits per limb +@cindex Limb size +The number of bits per limb. +@end deftypevr + +@defmac __GNU_MP_VERSION +@defmacx __GNU_MP_VERSION_MINOR +@defmacx __GNU_MP_VERSION_PATCHLEVEL +@cindex Version number +@cindex GMP version number +The major and minor GMP version, and patch level, respectively, as integers. +For GMP i.j, these numbers will be i, j, and 0, respectively. +For GMP i.j.k, these numbers will be i, j, and k, respectively. +@end defmac + +@deftypevr {Global Constant} {const char * const} gmp_version +@findex gmp_version +The GMP version number, as a null-terminated string, in the form ``i.j.k''. +This release is @nicode{"@value{VERSION}"}. Note that the format ``i.j'' was +used, before version 4.3.0, when k was zero. +@end deftypevr + +@defmac __GMP_CC +@defmacx __GMP_CFLAGS +The compiler and compiler flags, respectively, used when compiling GMP, as +strings. +@end defmac + + +@node Compatibility with older versions, Demonstration Programs, Useful Macros and Constants, GMP Basics +@section Compatibility with older versions +@cindex Compatibility with older versions +@cindex Past GMP versions +@cindex Upward compatibility + +This version of GMP is upwardly binary compatible with all 5.x, 4.x, and 3.x +versions, and upwardly compatible at the source level with all 2.x versions, +with the following exceptions. + +@itemize @bullet +@item +@code{mpn_gcd} had its source arguments swapped as of GMP 3.0, for consistency +with other @code{mpn} functions. + +@item +@code{mpf_get_prec} counted precision slightly differently in GMP 3.0 and +3.0.1, but in 3.1 reverted to the 2.x style. + +@item +@code{mpn_bdivmod}, documented as preliminary in GMP 4, has been removed. +@end itemize + +There are a number of compatibility issues between GMP 1 and GMP 2 that of +course also apply when porting applications from GMP 1 to GMP 5. Please +see the GMP 2 manual for details. + +@c @item Integer division functions round the result differently. The obsolete +@c functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv}, +@c @code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the +@c quotient towards +@c @ifinfo +@c @minus{}infinity). +@c @end ifinfo +@c @iftex +@c @tex +@c $-\infty$). +@c @end tex +@c @end iftex +@c There are a lot of functions for integer division, giving the user better +@c control over the rounding. + +@c @item The function @code{mpz_mod} now compute the true @strong{mod} function. + +@c @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use +@c @strong{mod} for reduction. + +@c @item The assignment functions for rational numbers do no longer canonicalize +@c their results. In the case a non-canonical result could arise from an +@c assignment, the user need to insert an explicit call to +@c @code{mpq_canonicalize}. This change was made for efficiency. + +@c @item Output generated by @code{mpz_out_raw} in this release cannot be read +@c by @code{mpz_inp_raw} in previous releases. This change was made for making +@c the file format truly portable between machines with different word sizes. + +@c @item Several @code{mpn} functions have changed. But they were intentionally +@c undocumented in previous releases. + +@c @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui} +@c are now implemented as macros, and thereby sometimes evaluate their +@c arguments multiple times. + +@c @item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1 +@c for 0^0. (In version 1, they yielded 0.) + +@c In version 1 of the library, @code{mpq_set_den} handled negative +@c denominators by copying the sign to the numerator. That is no longer done. + +@c Pure assignment functions do not canonicalize the assigned variable. It is +@c the responsibility of the user to canonicalize the assigned variable before +@c any arithmetic operations are performed on that variable. +@c Note that this is an incompatible change from version 1 of the library. + +@c @end enumerate + + +@need 1000 +@node Demonstration Programs, Efficiency, Compatibility with older versions, GMP Basics +@section Demonstration programs +@cindex Demonstration programs +@cindex Example programs +@cindex Sample programs +The @file{demos} subdirectory has some sample programs using GMP@. These +aren't built or installed, but there's a @file{Makefile} with rules for them. +For instance, + +@example +make pexpr +./pexpr 68^975+10 +@end example + +@noindent +The following programs are provided + +@itemize @bullet +@item +@cindex Expression parsing demo +@cindex Parsing expressions demo +@samp{pexpr} is an expression evaluator, the program used on the GMP web page. +@item +@cindex Expression parsing demo +@cindex Parsing expressions demo +The @samp{calc} subdirectory has a similar but simpler evaluator using +@command{lex} and @command{yacc}. +@item +@cindex Expression parsing demo +@cindex Parsing expressions demo +The @samp{expr} subdirectory is yet another expression evaluator, a library +designed for ease of use within a C program. See @file{demos/expr/README} for +more information. +@item +@cindex Factorization demo +@samp{factorize} is a Pollard-Rho factorization program. +@item +@samp{isprime} is a command-line interface to the @code{mpz_probab_prime_p} +function. +@item +@samp{primes} counts or lists primes in an interval, using a sieve. +@item +@samp{qcn} is an example use of @code{mpz_kronecker_ui} to estimate quadratic +class numbers. +@item +@cindex @code{perl} +@cindex GMP Perl module +@cindex Perl module +The @samp{perl} subdirectory is a comprehensive perl interface to GMP@. See +@file{demos/perl/INSTALL} for more information. Documentation is in POD +format in @file{demos/perl/GMP.pm}. +@end itemize + +As an aside, consideration has been given at various times to some sort of +expression evaluation within the main GMP library. Going beyond something +minimal quickly leads to matters like user-defined functions, looping, fixnums +for control variables, etc, which are considered outside the scope of GMP +(much closer to language interpreters or compilers, @xref{Language Bindings}). +Something simple for program input convenience may yet be a possibility, a +combination of the @file{expr} demo and the @file{pexpr} tree back-end +perhaps. But for now the above evaluators are offered as illustrations. + + +@need 1000 +@node Efficiency, Debugging, Demonstration Programs, GMP Basics +@section Efficiency +@cindex Efficiency + +@table @asis +@item Small Operands +@cindex Small operands +On small operands, the time for function call overheads and memory allocation +can be significant in comparison to actual calculation. This is unavoidable +in a general purpose variable precision library, although GMP attempts to be +as efficient as it can on both large and small operands. + +@item Static Linking +@cindex Static linking +On some CPUs, in particular the x86s, the static @file{libgmp.a} should be +used for maximum speed, since the PIC code in the shared @file{libgmp.so} will +have a small overhead on each function call and global data address. For many +programs this will be insignificant, but for long calculations there's a gain +to be had. + +@item Initializing and Clearing +@cindex Initializing and clearing +Avoid excessive initializing and clearing of variables, since this can be +quite time consuming, especially in comparison to otherwise fast operations +like addition. + +A language interpreter might want to keep a free list or stack of +initialized variables ready for use. It should be possible to integrate +something like that with a garbage collector too. + +@item Reallocations +@cindex Reallocations +An @code{mpz_t} or @code{mpq_t} variable used to hold successively increasing +values will have its memory repeatedly @code{realloc}ed, which could be quite +slow or could fragment memory, depending on the C library. If an application +can estimate the final size then @code{mpz_init2} or @code{mpz_realloc2} can +be called to allocate the necessary space from the beginning +(@pxref{Initializing Integers}). + +It doesn't matter if a size set with @code{mpz_init2} or @code{mpz_realloc2} +is too small, since all functions will do a further reallocation if necessary. +Badly overestimating memory required will waste space though. + +@item @code{2exp} Functions +@cindex @code{2exp} functions +It's up to an application to call functions like @code{mpz_mul_2exp} when +appropriate. General purpose functions like @code{mpz_mul} make no attempt to +identify powers of two or other special forms, because such inputs will +usually be very rare and testing every time would be wasteful. + +@item @code{ui} and @code{si} Functions +@cindex @code{ui} and @code{si} functions +The @code{ui} functions and the small number of @code{si} functions exist for +convenience and should be used where applicable. But if for example an +@code{mpz_t} contains a value that fits in an @code{unsigned long} there's no +need to extract it and call a @code{ui} function, just use the regular @code{mpz} +function. + +@item In-Place Operations +@cindex In-place operations +@code{mpz_abs}, @code{mpq_abs}, @code{mpf_abs}, @code{mpz_neg}, @code{mpq_neg} +and @code{mpf_neg} are fast when used for in-place operations like +@code{mpz_abs(x,x)}, since in the current implementation only a single field +of @code{x} needs changing. On suitable compilers (GCC for instance) this is +inlined too. + +@code{mpz_add_ui}, @code{mpz_sub_ui}, @code{mpf_add_ui} and @code{mpf_sub_ui} +benefit from an in-place operation like @code{mpz_add_ui(x,x,y)}, since +usually only one or two limbs of @code{x} will need to be changed. The same +applies to the full precision @code{mpz_add} etc if @code{y} is small. If +@code{y} is big then cache locality may be helped, but that's all. + +@code{mpz_mul} is currently the opposite, a separate destination is slightly +better. A call like @code{mpz_mul(x,x,y)} will, unless @code{y} is only one +limb, make a temporary copy of @code{x} before forming the result. Normally +that copying will only be a tiny fraction of the time for the multiply, so +this is not a particularly important consideration. + +@code{mpz_set}, @code{mpq_set}, @code{mpq_set_num}, @code{mpf_set}, etc, make +no attempt to recognise a copy of something to itself, so a call like +@code{mpz_set(x,x)} will be wasteful. Naturally that would never be written +deliberately, but if it might arise from two pointers to the same object then +a test to avoid it might be desirable. + +@example +if (x != y) + mpz_set (x, y); +@end example + +Note that it's never worth introducing extra @code{mpz_set} calls just to get +in-place operations. If a result should go to a particular variable then just +direct it there and let GMP take care of data movement. + +@item Divisibility Testing (Small Integers) +@cindex Divisibility testing +@code{mpz_divisible_ui_p} and @code{mpz_congruent_ui_p} are the best functions +for testing whether an @code{mpz_t} is divisible by an individual small +integer. They use an algorithm which is faster than @code{mpz_tdiv_ui}, but +which gives no useful information about the actual remainder, only whether +it's zero (or a particular value). + +However when testing divisibility by several small integers, it's best to take +a remainder modulo their product, to save multi-precision operations. For +instance to test whether a number is divisible by 23, 29 or 31 take a +remainder modulo @math{23@times{}29@times{}31 = 20677} and then test that. + +The division functions like @code{mpz_tdiv_q_ui} which give a quotient as well +as a remainder are generally a little slower than the remainder-only functions +like @code{mpz_tdiv_ui}. If the quotient is only rarely wanted then it's +probably best to just take a remainder and then go back and calculate the +quotient if and when it's wanted (@code{mpz_divexact_ui} can be used if the +remainder is zero). + +@item Rational Arithmetic +@cindex Rational arithmetic +The @code{mpq} functions operate on @code{mpq_t} values with no common factors +in the numerator and denominator. Common factors are checked-for and cast out +as necessary. In general, cancelling factors every time is the best approach +since it minimizes the sizes for subsequent operations. + +However, applications that know something about the factorization of the +values they're working with might be able to avoid some of the GCDs used for +canonicalization, or swap them for divisions. For example when multiplying by +a prime it's enough to check for factors of it in the denominator instead of +doing a full GCD@. Or when forming a big product it might be known that very +little cancellation will be possible, and so canonicalization can be left to +the end. + +The @code{mpq_numref} and @code{mpq_denref} macros give access to the +numerator and denominator to do things outside the scope of the supplied +@code{mpq} functions. @xref{Applying Integer Functions}. + +The canonical form for rationals allows mixed-type @code{mpq_t} and integer +additions or subtractions to be done directly with multiples of the +denominator. This will be somewhat faster than @code{mpq_add}. For example, + +@example +/* mpq increment */ +mpz_add (mpq_numref(q), mpq_numref(q), mpq_denref(q)); + +/* mpq += unsigned long */ +mpz_addmul_ui (mpq_numref(q), mpq_denref(q), 123UL); + +/* mpq -= mpz */ +mpz_submul (mpq_numref(q), mpq_denref(q), z); +@end example + +@item Number Sequences +@cindex Number sequences +Functions like @code{mpz_fac_ui}, @code{mpz_fib_ui} and @code{mpz_bin_uiui} +are designed for calculating isolated values. If a range of values is wanted +it's probably best to get a starting point and iterate from there. + +@item Text Input/Output +@cindex Text input/output +Hexadecimal or octal are suggested for input or output in text form. +Power-of-2 bases like these can be converted much more efficiently than other +bases, like decimal. For big numbers there's usually nothing of particular +interest to be seen in the digits, so the base doesn't matter much. + +Maybe we can hope octal will one day become the normal base for everyday use, +as proposed by King Charles XII of Sweden and later reformers. +@c Reference: Knuth volume 2 section 4.1, page 184 of second edition. :-) +@end table + + +@node Debugging, Profiling, Efficiency, GMP Basics +@section Debugging +@cindex Debugging + +@table @asis +@item Stack Overflow +@cindex Stack overflow +@cindex Segmentation violation +@cindex Bus error +Depending on the system, a segmentation violation or bus error might be the +only indication of stack overflow. See @samp{--enable-alloca} choices in +@ref{Build Options}, for how to address this. + +In new enough versions of GCC, @samp{-fstack-check} may be able to ensure an +overflow is recognised by the system before too much damage is done, or +@samp{-fstack-limit-symbol} or @samp{-fstack-limit-register} may be able to +add checking if the system itself doesn't do any (@pxref{Code Gen Options,, +Options for Code Generation, gcc, Using the GNU Compiler Collection (GCC)}). +These options must be added to the @samp{CFLAGS} used in the GMP build +(@pxref{Build Options}), adding them just to an application will have no +effect. Note also they're a slowdown, adding overhead to each function call +and each stack allocation. + +@item Heap Problems +@cindex Heap problems +@cindex Malloc problems +The most likely cause of application problems with GMP is heap corruption. +Failing to @code{init} GMP variables will have unpredictable effects, and +corruption arising elsewhere in a program may well affect GMP@. Initializing +GMP variables more than once or failing to clear them will cause memory leaks. + +@cindex Malloc debugger +In all such cases a @code{malloc} debugger is recommended. On a GNU or BSD +system the standard C library @code{malloc} has some diagnostic facilities, +see @ref{Allocation Debugging,, Allocation Debugging, libc, The GNU C Library +Reference Manual}, or @samp{man 3 malloc}. Other possibilities, in no +particular order, include + +@display +@uref{http://cs.ecs.baylor.edu/~donahoo/tools/ccmalloc/} +@uref{http://dmalloc.com/} +@uref{https://wiki.gnome.org/Apps/MemProf} +@end display + +The GMP default allocation routines in @file{memory.c} also have a simple +sentinel scheme which can be enabled with @code{#define DEBUG} in that file. +This is mainly designed for detecting buffer overruns during GMP development, +but might find other uses. + +@item Stack Backtraces +@cindex Stack backtrace +On some systems the compiler options GMP uses by default can interfere with +debugging. In particular on x86 and 68k systems @samp{-fomit-frame-pointer} +is used and this generally inhibits stack backtracing. Recompiling without +such options may help while debugging, though the usual caveats about it +potentially moving a memory problem or hiding a compiler bug will apply. + +@item GDB, the GNU Debugger +@cindex GDB +@cindex GNU Debugger +A sample @file{.gdbinit} is included in the distribution, showing how to call +some undocumented dump functions to print GMP variables from within GDB@. Note +that these functions shouldn't be used in final application code since they're +undocumented and may be subject to incompatible changes in future versions of +GMP. + +@item Source File Paths +GMP has multiple source files with the same name, in different directories. +For example @file{mpz}, @file{mpq} and @file{mpf} each have an +@file{init.c}. If the debugger can't already determine the right one it may +help to build with absolute paths on each C file. One way to do that is to +use a separate object directory with an absolute path to the source directory. + +@example +cd /my/build/dir +/my/source/dir/gmp-@value{VERSION}/configure +@end example + +This works via @code{VPATH}, and might require GNU @command{make}. +Alternately it might be possible to change the @code{.c.lo} rules +appropriately. + +@item Assertion Checking +@cindex Assertion checking +The build option @option{--enable-assert} is available to add some consistency +checks to the library (see @ref{Build Options}). These are likely to be of +limited value to most applications. Assertion failures are just as likely to +indicate memory corruption as a library or compiler bug. + +Applications using the low-level @code{mpn} functions, however, will benefit +from @option{--enable-assert} since it adds checks on the parameters of most +such functions, many of which have subtle restrictions on their usage. Note +however that only the generic C code has checks, not the assembly code, so +@option{--disable-assembly} should be used for maximum checking. + +@item Temporary Memory Checking +The build option @option{--enable-alloca=debug} arranges that each block of +temporary memory in GMP is allocated with a separate call to @code{malloc} (or +the allocation function set with @code{mp_set_memory_functions}). + +This can help a malloc debugger detect accesses outside the intended bounds, +or detect memory not released. In a normal build, on the other hand, +temporary memory is allocated in blocks which GMP divides up for its own use, +or may be allocated with a compiler builtin @code{alloca} which will go +nowhere near any malloc debugger hooks. + +@item Maximum Debuggability +To summarize the above, a GMP build for maximum debuggability would be + +@example +./configure --disable-shared --enable-assert \ + --enable-alloca=debug --disable-assembly CFLAGS=-g +@end example + +For C++, add @samp{--enable-cxx CXXFLAGS=-g}. + +@item Checker +@cindex Checker +@cindex GCC Checker +The GCC checker (@uref{https://savannah.nongnu.org/projects/checker/}) can be +used with GMP@. It contains a stub library which means GMP applications +compiled with checker can use a normal GMP build. + +A build of GMP with checking within GMP itself can be made. This will run +very very slowly. On GNU/Linux for example, + +@cindex @command{checkergcc} +@example +./configure --disable-assembly CC=checkergcc +@end example + +@option{--disable-assembly} must be used, since the GMP assembly code doesn't +support the checking scheme. The GMP C++ features cannot be used, since +current versions of checker (0.9.9.1) don't yet support the standard C++ +library. + +@item Valgrind +@cindex Valgrind +Valgrind (@uref{http://valgrind.org/}) is a memory checker for x86, ARM, MIPS, +PowerPC, and S/390. It translates and emulates machine instructions to do +strong checks for uninitialized data (at the level of individual bits), memory +accesses through bad pointers, and memory leaks. + +Valgrind does not always support every possible instruction, in particular +ones recently added to an ISA. Valgrind might therefore be incompatible with +a recent GMP or even a less recent GMP which is compiled using a recent GCC. + +GMP's assembly code sometimes promotes a read of the limbs to some larger size, +for efficiency. GMP will do this even at the start and end of a multilimb +operand, using naturally aligned operations on the larger type. This may lead +to benign reads outside of allocated areas, triggering complaints from +Valgrind. Valgrind's option @samp{--partial-loads-ok=yes} should help. + +@item Other Problems +Any suspected bug in GMP itself should be isolated to make sure it's not an +application problem, see @ref{Reporting Bugs}. +@end table + + +@node Profiling, Autoconf, Debugging, GMP Basics +@section Profiling +@cindex Profiling +@cindex Execution profiling +@cindex @code{--enable-profiling} + +Running a program under a profiler is a good way to find where it's spending +most time and where improvements can be best sought. The profiling choices +for a GMP build are as follows. + +@table @asis +@item @samp{--disable-profiling} +The default is to add nothing special for profiling. + +It should be possible to just compile the mainline of a program with @code{-p} +and use @command{prof} to get a profile consisting of timer-based sampling of +the program counter. Most of the GMP assembly code has the necessary symbol +information. + +This approach has the advantage of minimizing interference with normal program +operation, but on most systems the resolution of the sampling is quite low (10 +milliseconds for instance), requiring long runs to get accurate information. + +@item @samp{--enable-profiling=prof} +@cindex @code{prof} +Build with support for the system @command{prof}, which means @samp{-p} added +to the @samp{CFLAGS}. + +This provides call counting in addition to program counter sampling, which +allows the most frequently called routines to be identified, and an average +time spent in each routine to be determined. + +The x86 assembly code has support for this option, but on other processors +the assembly routines will be as if compiled without @samp{-p} and therefore +won't appear in the call counts. + +On some systems, such as GNU/Linux, @samp{-p} in fact means @samp{-pg} and in +this case @samp{--enable-profiling=gprof} described below should be used +instead. + +@item @samp{--enable-profiling=gprof} +@cindex @code{gprof} +Build with support for @command{gprof}, which means @samp{-pg} added to the +@samp{CFLAGS}. + +This provides call graph construction in addition to call counting and program +counter sampling, which makes it possible to count calls coming from different +locations. For example the number of calls to @code{mpn_mul} from +@code{mpz_mul} versus the number from @code{mpf_mul}. The program counter +sampling is still flat though, so only a total time in @code{mpn_mul} would be +accumulated, not a separate amount for each call site. + +The x86 assembly code has support for this option, but on other processors +the assembly routines will be as if compiled without @samp{-pg} and therefore +not be included in the call counts. + +On x86 and m68k systems @samp{-pg} and @samp{-fomit-frame-pointer} are +incompatible, so the latter is omitted from the default flags in that case, +which might result in poorer code generation. + +Incidentally, it should be possible to use the @command{gprof} program with a +plain @samp{--enable-profiling=prof} build. But in that case only the +@samp{gprof -p} flat profile and call counts can be expected to be valid, not +the @samp{gprof -q} call graph. + +@item @samp{--enable-profiling=instrument} +@cindex @code{-finstrument-functions} +@cindex @code{instrument-functions} +Build with the GCC option @samp{-finstrument-functions} added to the +@samp{CFLAGS} (@pxref{Code Gen Options,, Options for Code Generation, gcc, +Using the GNU Compiler Collection (GCC)}). + +This inserts special instrumenting calls at the start and end of each +function, allowing exact timing and full call graph construction. + +This instrumenting is not normally a standard system feature and will require +support from an external library, such as + +@cindex FunctionCheck +@cindex fnccheck +@display +@uref{https://sourceforge.net/projects/fnccheck/} +@end display + +This should be included in @samp{LIBS} during the GMP configure so that test +programs will link. For example, + +@example +./configure --enable-profiling=instrument LIBS=-lfc +@end example + +On a GNU system the C library provides dummy instrumenting functions, so +programs compiled with this option will link. In this case it's only +necessary to ensure the correct library is added when linking an application. + +The x86 assembly code supports this option, but on other processors the +assembly routines will be as if compiled without +@samp{-finstrument-functions} meaning time spent in them will effectively be +attributed to their caller. +@end table + + +@node Autoconf, Emacs, Profiling, GMP Basics +@section Autoconf +@cindex Autoconf + +Autoconf based applications can easily check whether GMP is installed. The +only thing to be noted is that GMP library symbols from version 3 onwards have +prefixes like @code{__gmpz}. The following therefore would be a simple test, + +@cindex @code{AC_CHECK_LIB} +@example +AC_CHECK_LIB(gmp, __gmpz_init) +@end example + +This just uses the default @code{AC_CHECK_LIB} actions for found or not found, +but an application that must have GMP would want to generate an error if not +found. For example, + +@example +AC_CHECK_LIB(gmp, __gmpz_init, , + [AC_MSG_ERROR([GNU MP not found, see https://gmplib.org/])]) +@end example + +If functions added in some particular version of GMP are required, then one of +those can be used when checking. For example @code{mpz_mul_si} was added in +GMP 3.1, + +@example +AC_CHECK_LIB(gmp, __gmpz_mul_si, , + [AC_MSG_ERROR( + [GNU MP not found, or not 3.1 or up, see https://gmplib.org/])]) +@end example + +An alternative would be to test the version number in @file{gmp.h} using say +@code{AC_EGREP_CPP}. That would make it possible to test the exact version, +if some particular sub-minor release is known to be necessary. + +In general it's recommended that applications should simply demand a new +enough GMP rather than trying to provide supplements for features not +available in past versions. + +Occasionally an application will need or want to know the size of a type at +configuration or preprocessing time, not just with @code{sizeof} in the code. +This can be done in the normal way with @code{mp_limb_t} etc, but GMP 4.0 or +up is best for this, since prior versions needed certain @samp{-D} defines on +systems using a @code{long long} limb. The following would suit Autoconf 2.50 +or up, + +@example +AC_CHECK_SIZEOF(mp_limb_t, , [#include ]) +@end example + + +@node Emacs, , Autoconf, GMP Basics +@section Emacs +@cindex Emacs +@cindex @code{info-lookup-symbol} + +@key{C-h C-i} (@code{info-lookup-symbol}) is a good way to find documentation +on C functions while editing (@pxref{Info Lookup, , Info Documentation Lookup, +emacs, The Emacs Editor}). + +The GMP manual can be included in such lookups by putting the following in +your @file{.emacs}, + +@c This isn't pretty, but there doesn't seem to be a better way (in emacs +@c 21.2 at least). info-lookup->mode-value could be used for the "assoc"s, +@c but that function isn't documented, whereas info-lookup-alist is. +@c +@example +(eval-after-load "info-look" + '(let ((mode-value (assoc 'c-mode (assoc 'symbol info-lookup-alist)))) + (setcar (nthcdr 3 mode-value) + (cons '("(gmp)Function Index" nil "^ -.* " "\\>") + (nth 3 mode-value))))) +@end example + + +@node Reporting Bugs, Integer Functions, GMP Basics, Top +@comment node-name, next, previous, up +@chapter Reporting Bugs +@cindex Reporting bugs +@cindex Bug reporting + +If you think you have found a bug in the GMP library, please investigate it +and report it. We have made this library available to you, and it is not too +much to ask you to report the bugs you find. + +Before you report a bug, check it's not already addressed in @ref{Known Build +Problems}, or perhaps @ref{Notes for Particular Systems}. You may also want +to check @uref{https://gmplib.org/} for patches for this release, or try a +recent snapshot from @uref{https://gmplib.org/download/snapshot/}. + +Please include the following in any report: + +@itemize @bullet +@item +The GMP version number, and if pre-packaged or patched then say so. + +@item +A test program that makes it possible for us to reproduce the bug. Include +instructions on how to run the program. + +@item +A description of what is wrong. If the results are incorrect, in what way. +If you get a crash, say so. + +@item +If you get a crash, include a stack backtrace from the debugger if it's +informative (@samp{where} in @command{gdb}, or @samp{$C} in @command{adb}). + +@item +Please do not send core dumps, executables or @command{strace}s. + +@item +The @samp{configure} options you used when building GMP, if any. + +@item +The output from @samp{configure}, as printed to stdout, with any options used. + +@item +The name of the compiler and its version. For @command{gcc}, get the version +with @samp{gcc -v}, otherwise perhaps @samp{what `which cc`}, or similar. + +@item +The output from running @samp{uname -a}. + +@item +The output from running @samp{./config.guess}, and from running +@samp{./configfsf.guess} (might be the same). + +@item +If the bug is related to @samp{configure}, then the compressed contents of +@file{config.log}. + +@item +If the bug is related to an @file{asm} file not assembling, then the contents +of @file{config.m4} and the offending line or lines from the temporary +@file{mpn/tmp-.s}. +@end itemize + +Please make an effort to produce a self-contained report, with something +definite that can be tested or debugged. Vague queries or piecemeal messages +are difficult to act on and don't help the development effort. + +It is not uncommon that an observed problem is actually due to a bug in the +compiler; the GMP code tends to explore interesting corners in compilers. + +If your bug report is good, we will do our best to help you get a corrected +version of the library; if the bug report is poor, we won't do anything about +it (except maybe ask you to send a better report). + +Send your report to: @email{gmp-bugs@@gmplib.org}. + +If you think something in this manual is unclear, or downright incorrect, or if +the language needs to be improved, please send a note to the same address. + + +@node Integer Functions, Rational Number Functions, Reporting Bugs, Top +@comment node-name, next, previous, up +@chapter Integer Functions +@cindex Integer functions + +This chapter describes the GMP functions for performing integer arithmetic. +These functions start with the prefix @code{mpz_}. + +GMP integers are stored in objects of type @code{mpz_t}. + +@menu +* Initializing Integers:: +* Assigning Integers:: +* Simultaneous Integer Init & Assign:: +* Converting Integers:: +* Integer Arithmetic:: +* Integer Division:: +* Integer Exponentiation:: +* Integer Roots:: +* Number Theoretic Functions:: +* Integer Comparisons:: +* Integer Logic and Bit Fiddling:: +* I/O of Integers:: +* Integer Random Numbers:: +* Integer Import and Export:: +* Miscellaneous Integer Functions:: +* Integer Special Functions:: +@end menu + +@node Initializing Integers, Assigning Integers, Integer Functions, Integer Functions +@comment node-name, next, previous, up +@section Initialization Functions +@cindex Integer initialization functions +@cindex Initialization functions + +The functions for integer arithmetic assume that all integer objects are +initialized. You do that by calling the function @code{mpz_init}. For +example, + +@example +@{ + mpz_t integ; + mpz_init (integ); + @dots{} + mpz_add (integ, @dots{}); + @dots{} + mpz_sub (integ, @dots{}); + + /* Unless the program is about to exit, do ... */ + mpz_clear (integ); +@} +@end example + +As you can see, you can store new values any number of times, once an +object is initialized. + +@deftypefun void mpz_init (mpz_t @var{x}) +Initialize @var{x}, and set its value to 0. +@end deftypefun + +@deftypefun void mpz_inits (mpz_t @var{x}, ...) +Initialize a NULL-terminated list of @code{mpz_t} variables, and set their +values to 0. +@end deftypefun + +@deftypefun void mpz_init2 (mpz_t @var{x}, mp_bitcnt_t @var{n}) +Initialize @var{x}, with space for @var{n}-bit numbers, and set its value to 0. +Calling this function instead of @code{mpz_init} or @code{mpz_inits} is never +necessary; reallocation is handled automatically by GMP when needed. + +While @var{n} defines the initial space, @var{x} will grow automatically in the +normal way, if necessary, for subsequent values stored. @code{mpz_init2} makes +it possible to avoid such reallocations if a maximum size is known in advance. + +In preparation for an operation, GMP often allocates one limb more than +ultimately needed. To make sure GMP will not perform reallocation for +@var{x}, you need to add the number of bits in @code{mp_limb_t} to @var{n}. +@end deftypefun + +@deftypefun void mpz_clear (mpz_t @var{x}) +Free the space occupied by @var{x}. Call this function for all @code{mpz_t} +variables when you are done with them. +@end deftypefun + +@deftypefun void mpz_clears (mpz_t @var{x}, ...) +Free the space occupied by a NULL-terminated list of @code{mpz_t} variables. +@end deftypefun + +@deftypefun void mpz_realloc2 (mpz_t @var{x}, mp_bitcnt_t @var{n}) +Change the space allocated for @var{x} to @var{n} bits. The value in @var{x} +is preserved if it fits, or is set to 0 if not. + +Calling this function is never necessary; reallocation is handled automatically +by GMP when needed. But this function can be used to increase the space for a +variable in order to avoid repeated automatic reallocations, or to decrease it +to give memory back to the heap. +@end deftypefun + + +@node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions +@comment node-name, next, previous, up +@section Assignment Functions +@cindex Integer assignment functions +@cindex Assignment functions + +These functions assign new values to already initialized integers +(@pxref{Initializing Integers}). + +@deftypefun void mpz_set (mpz_t @var{rop}, const mpz_t @var{op}) +@deftypefunx void mpz_set_ui (mpz_t @var{rop}, unsigned long int @var{op}) +@deftypefunx void mpz_set_si (mpz_t @var{rop}, signed long int @var{op}) +@deftypefunx void mpz_set_d (mpz_t @var{rop}, double @var{op}) +@deftypefunx void mpz_set_q (mpz_t @var{rop}, const mpq_t @var{op}) +@deftypefunx void mpz_set_f (mpz_t @var{rop}, const mpf_t @var{op}) +Set the value of @var{rop} from @var{op}. + +@code{mpz_set_d}, @code{mpz_set_q} and @code{mpz_set_f} truncate @var{op} to +make it an integer. +@end deftypefun + +@deftypefun int mpz_set_str (mpz_t @var{rop}, const char *@var{str}, int @var{base}) +Set the value of @var{rop} from @var{str}, a null-terminated C string in base +@var{base}. White space is allowed in the string, and is simply ignored. + +The @var{base} may vary from 2 to 62, or if @var{base} is 0, then the leading +characters are used: @code{0x} and @code{0X} for hexadecimal, @code{0b} and +@code{0B} for binary, @code{0} for octal, or decimal otherwise. + +For bases up to 36, case is ignored; upper-case and lower-case letters have +the same value. For bases 37 to 62, upper-case letters represent the usual +10..35 while lower-case letters represent 36..61. + +This function returns 0 if the entire string is a valid number in base +@var{base}. Otherwise it returns @minus{}1. +@c +@c It turns out that it is not entirely true that this function ignores +@c white-space. It does ignore it between digits, but not after a minus sign +@c or within or after ``0x''. Some thought was given to disallowing all +@c whitespace, but that would be an incompatible change, whitespace has been +@c documented as ignored ever since GMP 1. +@c +@end deftypefun + +@deftypefun void mpz_swap (mpz_t @var{rop1}, mpz_t @var{rop2}) +Swap the values @var{rop1} and @var{rop2} efficiently. +@end deftypefun + + +@node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions +@comment node-name, next, previous, up +@section Combined Initialization and Assignment Functions +@cindex Integer assignment functions +@cindex Assignment functions +@cindex Integer initialization functions +@cindex Initialization functions + +For convenience, GMP provides a parallel series of initialize-and-set functions +which initialize the output and then store the value there. These functions' +names have the form @code{mpz_init_set@dots{}} + +Here is an example of using one: + +@example +@{ + mpz_t pie; + mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); + @dots{} + mpz_sub (pie, @dots{}); + @dots{} + mpz_clear (pie); +@} +@end example + +@noindent +Once the integer has been initialized by any of the @code{mpz_init_set@dots{}} +functions, it can be used as the source or destination operand for the ordinary +integer functions. Don't use an initialize-and-set function on a variable +already initialized! + +@deftypefun void mpz_init_set (mpz_t @var{rop}, const mpz_t @var{op}) +@deftypefunx void mpz_init_set_ui (mpz_t @var{rop}, unsigned long int @var{op}) +@deftypefunx void mpz_init_set_si (mpz_t @var{rop}, signed long int @var{op}) +@deftypefunx void mpz_init_set_d (mpz_t @var{rop}, double @var{op}) +Initialize @var{rop} with limb space and set the initial numeric value from +@var{op}. +@end deftypefun + +@deftypefun int mpz_init_set_str (mpz_t @var{rop}, const char *@var{str}, int @var{base}) +Initialize @var{rop} and set its value like @code{mpz_set_str} (see its +documentation above for details). + +If the string is a correct base @var{base} number, the function returns 0; +if an error occurs it returns @minus{}1. @var{rop} is initialized even if +an error occurs. (I.e., you have to call @code{mpz_clear} for it.) +@end deftypefun + + +@node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions +@comment node-name, next, previous, up +@section Conversion Functions +@cindex Integer conversion functions +@cindex Conversion functions + +This section describes functions for converting GMP integers to standard C +types. Functions for converting @emph{to} GMP integers are described in +@ref{Assigning Integers} and @ref{I/O of Integers}. + +@deftypefun {unsigned long int} mpz_get_ui (const mpz_t @var{op}) +Return the value of @var{op} as an @code{unsigned long}. + +If @var{op} is too big to fit an @code{unsigned long} then just the least +significant bits that do fit are returned. The sign of @var{op} is ignored, +only the absolute value is used. +@end deftypefun + +@deftypefun {signed long int} mpz_get_si (const mpz_t @var{op}) +If @var{op} fits into a @code{signed long int} return the value of @var{op}. +Otherwise return the least significant part of @var{op}, with the same sign +as @var{op}. + +If @var{op} is too big to fit in a @code{signed long int}, the returned +result is probably not very useful. To find out if the value will fit, use +the function @code{mpz_fits_slong_p}. +@end deftypefun + +@deftypefun double mpz_get_d (const mpz_t @var{op}) +Convert @var{op} to a @code{double}, truncating if necessary (i.e.@: rounding +towards zero). + +If the exponent from the conversion is too big, the result is system +dependent. An infinity is returned where available. A hardware overflow trap +may or may not occur. +@end deftypefun + +@deftypefun double mpz_get_d_2exp (signed long int *@var{exp}, const mpz_t @var{op}) +Convert @var{op} to a @code{double}, truncating if necessary (i.e.@: rounding +towards zero), and returning the exponent separately. + +The return value is in the range @math{0.5@le{}@GMPabs{@var{d}}<1} and the +exponent is stored to @code{*@var{exp}}. @m{@var{d} * 2^{exp}, @var{d} * +2^@var{exp}} is the (truncated) @var{op} value. If @var{op} is zero, the +return is @math{0.0} and 0 is stored to @code{*@var{exp}}. + +@cindex @code{frexp} +This is similar to the standard C @code{frexp} function (@pxref{Normalization +Functions,,, libc, The GNU C Library Reference Manual}). +@end deftypefun + +@deftypefun {char *} mpz_get_str (char *@var{str}, int @var{base}, const mpz_t @var{op}) +Convert @var{op} to a string of digits in base @var{base}. The base argument +may vary from 2 to 62 or from @minus{}2 to @minus{}36. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +If @var{str} is @code{NULL}, the result string is allocated using the current +allocation function (@pxref{Custom Allocation}). The block will be +@code{strlen(str)+1} bytes, that being exactly enough for the string and +null-terminator. + +If @var{str} is not @code{NULL}, it should point to a block of storage large +enough for the result, that being @code{mpz_sizeinbase (@var{op}, @var{base}) ++ 2}. The two extra bytes are for a possible minus sign, and the +null-terminator. + +A pointer to the result string is returned, being either the allocated block, +or the given @var{str}. +@end deftypefun + + +@need 2000 +@node Integer Arithmetic, Integer Division, Converting Integers, Integer Functions +@comment node-name, next, previous, up +@section Arithmetic Functions +@cindex Integer arithmetic functions +@cindex Arithmetic functions + +@deftypefun void mpz_add (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_add_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{op1} + @var{op2}}. +@end deftypefun + +@deftypefun void mpz_sub (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_sub_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +@deftypefunx void mpz_ui_sub (mpz_t @var{rop}, unsigned long int @var{op1}, const mpz_t @var{op2}) +Set @var{rop} to @var{op1} @minus{} @var{op2}. +@end deftypefun + +@deftypefun void mpz_mul (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_mul_si (mpz_t @var{rop}, const mpz_t @var{op1}, long int @var{op2}) +@deftypefunx void mpz_mul_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{op1} @GMPtimes{} @var{op2}}. +@end deftypefun + +@deftypefun void mpz_addmul (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_addmul_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{rop} + @var{op1} @GMPtimes{} @var{op2}}. +@end deftypefun + +@deftypefun void mpz_submul (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_submul_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{rop} - @var{op1} @GMPtimes{} @var{op2}}. +@end deftypefun + +@deftypefun void mpz_mul_2exp (mpz_t @var{rop}, const mpz_t @var{op1}, mp_bitcnt_t @var{op2}) +@cindex Bit shift left +Set @var{rop} to @m{@var{op1} \times 2^{op2}, @var{op1} times 2 raised to +@var{op2}}. This operation can also be defined as a left shift by @var{op2} +bits. +@end deftypefun + +@deftypefun void mpz_neg (mpz_t @var{rop}, const mpz_t @var{op}) +Set @var{rop} to @minus{}@var{op}. +@end deftypefun + +@deftypefun void mpz_abs (mpz_t @var{rop}, const mpz_t @var{op}) +Set @var{rop} to the absolute value of @var{op}. +@end deftypefun + + +@need 2000 +@node Integer Division, Integer Exponentiation, Integer Arithmetic, Integer Functions +@section Division Functions +@cindex Integer division functions +@cindex Division functions + +Division is undefined if the divisor is zero. Passing a zero divisor to the +division or modulo functions (including the modular powering functions +@code{mpz_powm} and @code{mpz_powm_ui}) will cause an intentional division by +zero. This lets a program handle arithmetic exceptions in these functions the +same way as for normal C @code{int} arithmetic. + +@c Separate deftypefun groups for cdiv, fdiv and tdiv produce a blank line +@c between each, and seem to let tex do a better job of page breaks than an +@c @sp 1 in the middle of one big set. + +@deftypefun void mpz_cdiv_q (mpz_t @var{q}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_cdiv_r (mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_cdiv_qr (mpz_t @var{q}, mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@maybepagebreak +@deftypefunx {unsigned long int} mpz_cdiv_q_ui (mpz_t @var{q}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{r}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_cdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, @w{const mpz_t @var{n}}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_cdiv_ui (const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@maybepagebreak +@deftypefunx void mpz_cdiv_q_2exp (mpz_t @var{q}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@deftypefunx void mpz_cdiv_r_2exp (mpz_t @var{r}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@end deftypefun + +@deftypefun void mpz_fdiv_q (mpz_t @var{q}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_fdiv_r (mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_fdiv_qr (mpz_t @var{q}, mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@maybepagebreak +@deftypefunx {unsigned long int} mpz_fdiv_q_ui (mpz_t @var{q}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{r}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_fdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, @w{const mpz_t @var{n}}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_fdiv_ui (const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@maybepagebreak +@deftypefunx void mpz_fdiv_q_2exp (mpz_t @var{q}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@deftypefunx void mpz_fdiv_r_2exp (mpz_t @var{r}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@end deftypefun + +@deftypefun void mpz_tdiv_q (mpz_t @var{q}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_tdiv_r (mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_tdiv_qr (mpz_t @var{q}, mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@maybepagebreak +@deftypefunx {unsigned long int} mpz_tdiv_q_ui (mpz_t @var{q}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_tdiv_r_ui (mpz_t @var{r}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_tdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, @w{const mpz_t @var{n}}, @w{unsigned long int @var{d}}) +@deftypefunx {unsigned long int} mpz_tdiv_ui (const mpz_t @var{n}, @w{unsigned long int @var{d}}) +@maybepagebreak +@deftypefunx void mpz_tdiv_q_2exp (mpz_t @var{q}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@deftypefunx void mpz_tdiv_r_2exp (mpz_t @var{r}, const mpz_t @var{n}, @w{mp_bitcnt_t @var{b}}) +@cindex Bit shift right + +@sp 1 +Divide @var{n} by @var{d}, forming a quotient @var{q} and/or remainder +@var{r}. For the @code{2exp} functions, @m{@var{d}=2^b, @var{d}=2^@var{b}}. +The rounding is in three styles, each suiting different applications. + +@itemize @bullet +@item +@code{cdiv} rounds @var{q} up towards @m{+\infty, +infinity}, and @var{r} will +have the opposite sign to @var{d}. The @code{c} stands for ``ceil''. + +@item +@code{fdiv} rounds @var{q} down towards @m{-\infty, @minus{}infinity}, and +@var{r} will have the same sign as @var{d}. The @code{f} stands for +``floor''. + +@item +@code{tdiv} rounds @var{q} towards zero, and @var{r} will have the same sign +as @var{n}. The @code{t} stands for ``truncate''. +@end itemize + +In all cases @var{q} and @var{r} will satisfy +@m{@var{n}=@var{q}@var{d}+@var{r}, @var{n}=@var{q}*@var{d}+@var{r}}, and +@var{r} will satisfy @math{0@le{}@GMPabs{@var{r}}<@GMPabs{@var{d}}}. + +The @code{q} functions calculate only the quotient, the @code{r} functions +only the remainder, and the @code{qr} functions calculate both. Note that for +@code{qr} the same variable cannot be passed for both @var{q} and @var{r}, or +results will be unpredictable. + +For the @code{ui} variants the return value is the remainder, and in fact +returning the remainder is all the @code{div_ui} functions do. For +@code{tdiv} and @code{cdiv} the remainder can be negative, so for those the +return value is the absolute value of the remainder. + +For the @code{2exp} variants the divisor is @m{2^b,2^@var{b}}. These +functions are implemented as right shifts and bit masks, but of course they +round the same as the other functions. + +For positive @var{n} both @code{mpz_fdiv_q_2exp} and @code{mpz_tdiv_q_2exp} +are simple bitwise right shifts. For negative @var{n}, @code{mpz_fdiv_q_2exp} +is effectively an arithmetic right shift treating @var{n} as two's complement +the same as the bitwise logical functions do, whereas @code{mpz_tdiv_q_2exp} +effectively treats @var{n} as sign and magnitude. +@end deftypefun + +@deftypefun void mpz_mod (mpz_t @var{r}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{r}, const mpz_t @var{n}, @w{unsigned long int @var{d}}) +Set @var{r} to @var{n} @code{mod} @var{d}. The sign of the divisor is +ignored; the result is always non-negative. + +@code{mpz_mod_ui} is identical to @code{mpz_fdiv_r_ui} above, returning the +remainder as well as setting @var{r}. See @code{mpz_fdiv_ui} above if only +the return value is wanted. +@end deftypefun + +@deftypefun void mpz_divexact (mpz_t @var{q}, const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx void mpz_divexact_ui (mpz_t @var{q}, const mpz_t @var{n}, unsigned long @var{d}) +@cindex Exact division functions +Set @var{q} to @var{n}/@var{d}. These functions produce correct results only +when it is known in advance that @var{d} divides @var{n}. + +These routines are much faster than the other division functions, and are the +best choice when exact division is known to occur, for example reducing a +rational to lowest terms. +@end deftypefun + +@deftypefun int mpz_divisible_p (const mpz_t @var{n}, const mpz_t @var{d}) +@deftypefunx int mpz_divisible_ui_p (const mpz_t @var{n}, unsigned long int @var{d}) +@deftypefunx int mpz_divisible_2exp_p (const mpz_t @var{n}, mp_bitcnt_t @var{b}) +@cindex Divisibility functions +Return non-zero if @var{n} is exactly divisible by @var{d}, or in the case of +@code{mpz_divisible_2exp_p} by @m{2^b,2^@var{b}}. + +@var{n} is divisible by @var{d} if there exists an integer @var{q} satisfying +@math{@var{n} = @var{q}@GMPmultiply{}@var{d}}. Unlike the other division +functions, @math{@var{d}=0} is accepted and following the rule it can be seen +that only 0 is considered divisible by 0. +@end deftypefun + +@deftypefun int mpz_congruent_p (const mpz_t @var{n}, const mpz_t @var{c}, const mpz_t @var{d}) +@deftypefunx int mpz_congruent_ui_p (const mpz_t @var{n}, unsigned long int @var{c}, unsigned long int @var{d}) +@deftypefunx int mpz_congruent_2exp_p (const mpz_t @var{n}, const mpz_t @var{c}, mp_bitcnt_t @var{b}) +@cindex Divisibility functions +@cindex Congruence functions +Return non-zero if @var{n} is congruent to @var{c} modulo @var{d}, or in the +case of @code{mpz_congruent_2exp_p} modulo @m{2^b,2^@var{b}}. + +@var{n} is congruent to @var{c} mod @var{d} if there exists an integer @var{q} +satisfying @math{@var{n} = @var{c} + @var{q}@GMPmultiply{}@var{d}}. Unlike +the other division functions, @math{@var{d}=0} is accepted and following the +rule it can be seen that @var{n} and @var{c} are considered congruent mod 0 +only when exactly equal. +@end deftypefun + + +@need 2000 +@node Integer Exponentiation, Integer Roots, Integer Division, Integer Functions +@section Exponentiation Functions +@cindex Integer exponentiation functions +@cindex Exponentiation functions +@cindex Powering functions + +@deftypefun void mpz_powm (mpz_t @var{rop}, const mpz_t @var{base}, const mpz_t @var{exp}, const mpz_t @var{mod}) +@deftypefunx void mpz_powm_ui (mpz_t @var{rop}, const mpz_t @var{base}, unsigned long int @var{exp}, const mpz_t @var{mod}) +Set @var{rop} to @m{base^{exp} \bmod mod, (@var{base} raised to @var{exp}) +modulo @var{mod}}. + +Negative @var{exp} is supported if the inverse @mm{@var{base}@sup{-1} @bmod +@var{mod}, @var{base}^(-1) @bmod @var{mod}} exists (see @code{mpz_invert} in +@ref{Number Theoretic Functions}). If an inverse doesn't exist then a divide +by zero is raised. +@end deftypefun + +@deftypefun void mpz_powm_sec (mpz_t @var{rop}, const mpz_t @var{base}, const mpz_t @var{exp}, const mpz_t @var{mod}) +Set @var{rop} to @m{base^{exp} \bmod @var{mod}, (@var{base} raised to @var{exp}) +modulo @var{mod}}. + +It is required that @math{@var{exp} > 0} and that @var{mod} is odd. + +This function is designed to take the same time and have the same cache access +patterns for any two same-size arguments, assuming that function arguments are +placed at the same position and that the machine state is identical upon +function entry. This function is intended for cryptographic purposes, where +resilience to side-channel attacks is desired. +@end deftypefun + +@deftypefun void mpz_pow_ui (mpz_t @var{rop}, const mpz_t @var{base}, unsigned long int @var{exp}) +@deftypefunx void mpz_ui_pow_ui (mpz_t @var{rop}, unsigned long int @var{base}, unsigned long int @var{exp}) +Set @var{rop} to @m{base^{exp}, @var{base} raised to @var{exp}}. The case +@math{0^0} yields 1. +@end deftypefun + + +@need 2000 +@node Integer Roots, Number Theoretic Functions, Integer Exponentiation, Integer Functions +@section Root Extraction Functions +@cindex Integer root functions +@cindex Root extraction functions + +@deftypefun int mpz_root (mpz_t @var{rop}, const mpz_t @var{op}, unsigned long int @var{n}) +Set @var{rop} to @m{\lfloor\root n \of {op}\rfloor@C{},} the truncated integer +part of the @var{n}th root of @var{op}. Return non-zero if the computation +was exact, i.e., if @var{op} is @var{rop} to the @var{n}th power. +@end deftypefun + +@deftypefun void mpz_rootrem (mpz_t @var{root}, mpz_t @var{rem}, const mpz_t @var{u}, unsigned long int @var{n}) +Set @var{root} to @m{\lfloor\root n \of {u}\rfloor@C{},} the truncated +integer part of the @var{n}th root of @var{u}. Set @var{rem} to the +remainder, @m{(@var{u} - @var{root}^n), +@var{u}@minus{}@var{root}**@var{n}}. +@end deftypefun + +@deftypefun void mpz_sqrt (mpz_t @var{rop}, const mpz_t @var{op}) +Set @var{rop} to @m{\lfloor\sqrt{@var{op}}\rfloor@C{},} the truncated +integer part of the square root of @var{op}. +@end deftypefun + +@deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, const mpz_t @var{op}) +Set @var{rop1} to @m{\lfloor\sqrt{@var{op}}\rfloor, the truncated integer part +of the square root of @var{op}}, like @code{mpz_sqrt}. Set @var{rop2} to the +remainder @m{(@var{op} - @var{rop1}^2), +@var{op}@minus{}@var{rop1}*@var{rop1}}, which will be zero if @var{op} is a +perfect square. + +If @var{rop1} and @var{rop2} are the same variable, the results are +undefined. +@end deftypefun + +@deftypefun int mpz_perfect_power_p (const mpz_t @var{op}) +@cindex Perfect power functions +@cindex Root testing functions +Return non-zero if @var{op} is a perfect power, i.e., if there exist integers +@m{a,@var{a}} and @m{b,@var{b}}, with @m{b>1, @var{b}>1}, such that +@m{@var{op}=a^b, @var{op} equals @var{a} raised to the power @var{b}}. + +Under this definition both 0 and 1 are considered to be perfect powers. +Negative values of @var{op} are accepted, but of course can only be odd +perfect powers. +@end deftypefun + +@deftypefun int mpz_perfect_square_p (const mpz_t @var{op}) +@cindex Perfect square functions +@cindex Root testing functions +Return non-zero if @var{op} is a perfect square, i.e., if the square root of +@var{op} is an integer. Under this definition both 0 and 1 are considered to +be perfect squares. +@end deftypefun + + +@need 2000 +@node Number Theoretic Functions, Integer Comparisons, Integer Roots, Integer Functions +@section Number Theoretic Functions +@cindex Number theoretic functions + +@deftypefun int mpz_probab_prime_p (const mpz_t @var{n}, int @var{reps}) +@cindex Prime testing functions +@cindex Probable prime testing functions +Determine whether @var{n} is prime. Return 2 if @var{n} is definitely prime, +return 1 if @var{n} is probably prime (without being certain), or return 0 if +@var{n} is definitely non-prime. + +This function performs some trial divisions, a Baillie-PSW probable prime +test, then @var{reps-24} Miller-Rabin probabilistic primality tests. A +higher @var{reps} value will reduce the chances of a non-prime being +identified as ``probably prime''. A composite number will be identified as a +prime with an asymptotic probability of less than @m{4^{-reps},4^(-@var{reps})}. +Reasonable values of @var{reps} are between 15 and 50. + +GMP versions up to and including 6.1.2 did not use the Baillie-PSW +primality test. In those older versions of GMP, this function performed +@var{reps} Miller-Rabin tests. +@end deftypefun + +@deftypefun void mpz_nextprime (mpz_t @var{rop}, const mpz_t @var{op}) +@cindex Next prime function +Set @var{rop} to the next prime greater than @var{op}. +@end deftypefun + +@deftypefun int mpz_prevprime (mpz_t @var{rop}, const mpz_t @var{op}) +@cindex Previous prime function +Set @var{rop} to the greatest prime less than @var{op}. + +If a previous prime doesn't exist (i.e. @var{op} < 3), rop is unchanged and +0 is returned. + +Return 1 if @var{rop} is a probably prime, and 2 if @var{rop} is definitely +prime. + +These functions use a probabilistic algorithm to identify primes. For +practical purposes it's adequate, the chance of a composite passing will be +extremely small. +@end deftypefun + +@c mpz_prime_p not implemented as of gmp 3.0. + +@c @deftypefun int mpz_prime_p (const mpz_t @var{n}) +@c Return non-zero if @var{n} is prime and zero if @var{n} is a non-prime. +@c This function is far slower than @code{mpz_probab_prime_p}, but then it +@c never returns non-zero for composite numbers. + +@c (For practical purposes, using @code{mpz_probab_prime_p} is adequate. +@c The likelihood of a programming error or hardware malfunction is orders +@c of magnitudes greater than the likelihood for a composite to pass as a +@c prime, if the @var{reps} argument is in the suggested range.) +@c @end deftypefun + +@deftypefun void mpz_gcd (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@cindex Greatest common divisor functions +@cindex GCD functions +Set @var{rop} to the greatest common divisor of @var{op1} and @var{op2}. The +result is always positive even if one or both input operands are negative. +Except if both inputs are zero; then this function defines @math{gcd(0,0) = 0}. +@end deftypefun + +@deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long int @var{op2}) +Compute the greatest common divisor of @var{op1} and @var{op2}. If +@var{rop} is not @code{NULL}, store the result there. + +If the result is small enough to fit in an @code{unsigned long int}, it is +returned. If the result does not fit, 0 is returned, and the result is equal +to the argument @var{op1}. Note that the result will always fit if @var{op2} +is non-zero. +@end deftypefun + +@deftypefun void mpz_gcdext (mpz_t @var{g}, mpz_t @var{s}, mpz_t @var{t}, const mpz_t @var{a}, const mpz_t @var{b}) +@cindex Extended GCD +@cindex GCD extended +Set @var{g} to the greatest common divisor of @var{a} and @var{b}, and in +addition set @var{s} and @var{t} to coefficients satisfying +@math{@var{a}@GMPmultiply{}@var{s} + @var{b}@GMPmultiply{}@var{t} = @var{g}}. +The value in @var{g} is always positive, even if one or both of @var{a} and +@var{b} are negative (or zero if both inputs are zero). The values in @var{s} +and @var{t} are chosen such that normally, @math{@GMPabs{@var{s}} < +@GMPabs{@var{b}} / (2 @var{g})} and @math{@GMPabs{@var{t}} < @GMPabs{@var{a}} +/ (2 @var{g})}, and these relations define @var{s} and @var{t} uniquely. There +are a few exceptional cases: + +If @math{@GMPabs{@var{a}} = @GMPabs{@var{b}}}, then @math{@var{s} = 0}, +@math{@var{t} = sgn(@var{b})}. + +Otherwise, @math{@var{s} = sgn(@var{a})} if @math{@var{b} = 0} or +@math{@GMPabs{@var{b}} = 2 @var{g}}, and @math{@var{t} = sgn(@var{b})} if +@math{@var{a} = 0} or @math{@GMPabs{@var{a}} = 2 @var{g}}. + +In all cases, @math{@var{s} = 0} if and only if @math{@var{g} = +@GMPabs{@var{b}}}, i.e., if @var{b} divides @var{a} or @math{@var{a} = @var{b} += 0}. + +If @var{t} or @var{g} is @code{NULL} then that value is not computed. +@end deftypefun + +@deftypefun void mpz_lcm (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx void mpz_lcm_ui (mpz_t @var{rop}, const mpz_t @var{op1}, unsigned long @var{op2}) +@cindex Least common multiple functions +@cindex LCM functions +Set @var{rop} to the least common multiple of @var{op1} and @var{op2}. +@var{rop} is always positive, irrespective of the signs of @var{op1} and +@var{op2}. @var{rop} will be zero if either @var{op1} or @var{op2} is zero. +@end deftypefun + +@deftypefun int mpz_invert (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +@cindex Modular inverse functions +@cindex Inverse modulo functions +Compute the inverse of @var{op1} modulo @var{op2} and put the result in +@var{rop}. If the inverse exists, the return value is non-zero and @var{rop} +will satisfy @math{0 @le{} @var{rop} < @GMPabs{@var{op2}}} (with @math{@var{rop} += 0} possible only when @math{@GMPabs{@var{op2}} = 1}, i.e., in the +somewhat degenerate zero ring). If an inverse doesn't +exist the return value is zero and @var{rop} is undefined. The behaviour of +this function is undefined when @var{op2} is zero. +@end deftypefun + +@deftypefun int mpz_jacobi (const mpz_t @var{a}, const mpz_t @var{b}) +@cindex Jacobi symbol functions +Calculate the Jacobi symbol @m{\left(a \over b\right), +(@var{a}/@var{b})}. This is defined only for @var{b} odd. +@end deftypefun + +@deftypefun int mpz_legendre (const mpz_t @var{a}, const mpz_t @var{p}) +@cindex Legendre symbol functions +Calculate the Legendre symbol @m{\left(a \over p\right), +(@var{a}/@var{p})}. This is defined only for @var{p} an odd positive +prime, and for such @var{p} it's identical to the Jacobi symbol. +@end deftypefun + +@deftypefun int mpz_kronecker (const mpz_t @var{a}, const mpz_t @var{b}) +@deftypefunx int mpz_kronecker_si (const mpz_t @var{a}, long @var{b}) +@deftypefunx int mpz_kronecker_ui (const mpz_t @var{a}, unsigned long @var{b}) +@deftypefunx int mpz_si_kronecker (long @var{a}, const mpz_t @var{b}) +@deftypefunx int mpz_ui_kronecker (unsigned long @var{a}, const mpz_t @var{b}) +@cindex Kronecker symbol functions +Calculate the Jacobi symbol @m{\left(a \over b\right), +(@var{a}/@var{b})} with the Kronecker extension @m{\left(a \over +2\right) = \left(2 \over a\right), (a/2)=(2/a)} when @math{a} odd, or +@m{\left(a \over 2\right) = 0, (a/2)=0} when @math{a} even. + +When @var{b} is odd the Jacobi symbol and Kronecker symbol are +identical, so @code{mpz_kronecker_ui} etc can be used for mixed +precision Jacobi symbols too. + +For more information see Henri Cohen section 1.4.2 (@pxref{References}), +or any number theory textbook. See also the example program +@file{demos/qcn.c} which uses @code{mpz_kronecker_ui}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpz_remove (mpz_t @var{rop}, const mpz_t @var{op}, const mpz_t @var{f}) +@cindex Remove factor functions +@cindex Factor removal functions +Remove all occurrences of the factor @var{f} from @var{op} and store the +result in @var{rop}. The return value is how many such occurrences were +removed. +@end deftypefun + +@deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{n}) +@deftypefunx void mpz_2fac_ui (mpz_t @var{rop}, unsigned long int @var{n}) +@deftypefunx void mpz_mfac_uiui (mpz_t @var{rop}, unsigned long int @var{n}, unsigned long int @var{m}) +@cindex Factorial functions +Set @var{rop} to the factorial of @var{n}: @code{mpz_fac_ui} computes the plain factorial @var{n}!, +@code{mpz_2fac_ui} computes the double-factorial @var{n}!!, and @code{mpz_mfac_uiui} the +@var{m}-multi-factorial @m{n!^{(m)}, @var{n}!^(@var{m})}. +@end deftypefun + +@deftypefun void mpz_primorial_ui (mpz_t @var{rop}, unsigned long int @var{n}) +@cindex Primorial functions +Set @var{rop} to the primorial of @var{n}, i.e. the product of all positive +prime numbers @math{@le{}@var{n}}. +@end deftypefun + +@deftypefun void mpz_bin_ui (mpz_t @var{rop}, const mpz_t @var{n}, unsigned long int @var{k}) +@deftypefunx void mpz_bin_uiui (mpz_t @var{rop}, unsigned long int @var{n}, @w{unsigned long int @var{k}}) +@cindex Binomial coefficient functions +Compute the binomial coefficient @m{\left({n}\atop{k}\right), @var{n} over +@var{k}} and store the result in @var{rop}. Negative values of @var{n} are +supported by @code{mpz_bin_ui}, using the identity +@m{\left({-n}\atop{k}\right) = (-1)^k \left({n+k-1}\atop{k}\right), +bin(-n@C{}k) = (-1)^k * bin(n+k-1@C{}k)}, see Knuth volume 1 section 1.2.6 +part G. +@end deftypefun + +@deftypefun void mpz_fib_ui (mpz_t @var{fn}, unsigned long int @var{n}) +@deftypefunx void mpz_fib2_ui (mpz_t @var{fn}, mpz_t @var{fnsub1}, unsigned long int @var{n}) +@cindex Fibonacci sequence functions +@code{mpz_fib_ui} sets @var{fn} to @m{F_n,F[n]}, the @var{n}th Fibonacci +number. @code{mpz_fib2_ui} sets @var{fn} to @m{F_n,F[n]}, and @var{fnsub1} to +@m{F_{n-1},F[n-1]}. + +These functions are designed for calculating isolated Fibonacci numbers. When +a sequence of values is wanted it's best to start with @code{mpz_fib2_ui} and +iterate the defining @m{F_{n+1} = F_n + F_{n-1}, F[n+1]=F[n]+F[n-1]} or +similar. +@end deftypefun + +@deftypefun void mpz_lucnum_ui (mpz_t @var{ln}, unsigned long int @var{n}) +@deftypefunx void mpz_lucnum2_ui (mpz_t @var{ln}, mpz_t @var{lnsub1}, unsigned long int @var{n}) +@cindex Lucas number functions +@code{mpz_lucnum_ui} sets @var{ln} to @m{L_n,L[n]}, the @var{n}th Lucas +number. @code{mpz_lucnum2_ui} sets @var{ln} to @m{L_n,L[n]}, and @var{lnsub1} +to @m{L_{n-1},L[n-1]}. + +These functions are designed for calculating isolated Lucas numbers. When a +sequence of values is wanted it's best to start with @code{mpz_lucnum2_ui} and +iterate the defining @m{L_{n+1} = L_n + L_{n-1}, L[n+1]=L[n]+L[n-1]} or +similar. + +The Fibonacci numbers and Lucas numbers are related sequences, so it's never +necessary to call both @code{mpz_fib2_ui} and @code{mpz_lucnum2_ui}. The +formulas for going from Fibonacci to Lucas can be found in @ref{Lucas Numbers +Algorithm}, the reverse is straightforward too. +@end deftypefun + + +@node Integer Comparisons, Integer Logic and Bit Fiddling, Number Theoretic Functions, Integer Functions +@comment node-name, next, previous, up +@section Comparison Functions +@cindex Integer comparison functions +@cindex Comparison functions + +@deftypefn Function int mpz_cmp (const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefnx Function int mpz_cmp_d (const mpz_t @var{op1}, double @var{op2}) +@deftypefnx Macro int mpz_cmp_si (const mpz_t @var{op1}, signed long int @var{op2}) +@deftypefnx Macro int mpz_cmp_ui (const mpz_t @var{op1}, unsigned long int @var{op2}) +Compare @var{op1} and @var{op2}. Return a positive value if @math{@var{op1} > +@var{op2}}, zero if @math{@var{op1} = @var{op2}}, or a negative value if +@math{@var{op1} < @var{op2}}. + +@code{mpz_cmp_ui} and @code{mpz_cmp_si} are macros and will evaluate their +arguments more than once. @code{mpz_cmp_d} can be called with an infinity, +but results are undefined for a NaN. +@end deftypefn + +@deftypefn Function int mpz_cmpabs (const mpz_t @var{op1}, const mpz_t @var{op2}) +@deftypefnx Function int mpz_cmpabs_d (const mpz_t @var{op1}, double @var{op2}) +@deftypefnx Function int mpz_cmpabs_ui (const mpz_t @var{op1}, unsigned long int @var{op2}) +Compare the absolute values of @var{op1} and @var{op2}. Return a positive +value if @math{@GMPabs{@var{op1}} > @GMPabs{@var{op2}}}, zero if +@math{@GMPabs{@var{op1}} = @GMPabs{@var{op2}}}, or a negative value if +@math{@GMPabs{@var{op1}} < @GMPabs{@var{op2}}}. + +@code{mpz_cmpabs_d} can be called with an infinity, but results are undefined +for a NaN. +@end deftypefn + +@deftypefn Macro int mpz_sgn (const mpz_t @var{op}) +@cindex Sign tests +@cindex Integer sign tests +Return @math{+1} if @math{@var{op} > 0}, 0 if @math{@var{op} = 0}, and +@math{-1} if @math{@var{op} < 0}. + +This function is actually implemented as a macro. It evaluates its argument +multiple times. +@end deftypefn + + +@node Integer Logic and Bit Fiddling, I/O of Integers, Integer Comparisons, Integer Functions +@comment node-name, next, previous, up +@section Logical and Bit Manipulation Functions +@cindex Logical functions +@cindex Bit manipulation functions +@cindex Integer logical functions +@cindex Integer bit manipulation functions + +These functions behave as if two's complement arithmetic were used (although +sign-magnitude is the actual implementation). The least significant bit is +number 0. + +@deftypefun void mpz_and (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +Set @var{rop} to @var{op1} bitwise-and @var{op2}. +@end deftypefun + +@deftypefun void mpz_ior (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +Set @var{rop} to @var{op1} bitwise inclusive-or @var{op2}. +@end deftypefun + +@deftypefun void mpz_xor (mpz_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}) +Set @var{rop} to @var{op1} bitwise exclusive-or @var{op2}. +@end deftypefun + +@deftypefun void mpz_com (mpz_t @var{rop}, const mpz_t @var{op}) +Set @var{rop} to the one's complement of @var{op}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpz_popcount (const mpz_t @var{op}) +If @math{@var{op}@ge{}0}, return the population count of @var{op}, which is the +number of 1 bits in the binary representation. If @math{@var{op}<0}, the +number of 1s is infinite, and the return value is the largest possible +@code{mp_bitcnt_t}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpz_hamdist (const mpz_t @var{op1}, const mpz_t @var{op2}) +If @var{op1} and @var{op2} are both @math{@ge{}0} or both @math{<0}, return the +hamming distance between the two operands, which is the number of bit positions +where @var{op1} and @var{op2} have different bit values. If one operand is +@math{@ge{}0} and the other @math{<0} then the number of bits different is +infinite, and the return value is the largest possible @code{mp_bitcnt_t}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpz_scan0 (const mpz_t @var{op}, mp_bitcnt_t @var{starting_bit}) +@deftypefunx {mp_bitcnt_t} mpz_scan1 (const mpz_t @var{op}, mp_bitcnt_t @var{starting_bit}) +@cindex Bit scanning functions +@cindex Scan bit functions +Scan @var{op}, starting from bit @var{starting_bit}, towards more significant +bits, until the first 0 or 1 bit (respectively) is found. Return the index of +the found bit. + +If the bit at @var{starting_bit} is already what's sought, then +@var{starting_bit} is returned. + +If there's no bit found, then the largest possible @code{mp_bitcnt_t} is +returned. This will happen in @code{mpz_scan0} past the end of a negative +number, or @code{mpz_scan1} past the end of a nonnegative number. +@end deftypefun + +@deftypefun void mpz_setbit (mpz_t @var{rop}, mp_bitcnt_t @var{bit_index}) +Set bit @var{bit_index} in @var{rop}. +@end deftypefun + +@deftypefun void mpz_clrbit (mpz_t @var{rop}, mp_bitcnt_t @var{bit_index}) +Clear bit @var{bit_index} in @var{rop}. +@end deftypefun + +@deftypefun void mpz_combit (mpz_t @var{rop}, mp_bitcnt_t @var{bit_index}) +Complement bit @var{bit_index} in @var{rop}. +@end deftypefun + +@deftypefun int mpz_tstbit (const mpz_t @var{op}, mp_bitcnt_t @var{bit_index}) +Test bit @var{bit_index} in @var{op} and return 0 or 1 accordingly. +@end deftypefun + +Shifting is also possible using multiplication (@ref{Integer Arithmetic}) and +division (@ref{Integer Division}), in particular the @code{2exp} functions. + +@node I/O of Integers, Integer Random Numbers, Integer Logic and Bit Fiddling, Integer Functions +@comment node-name, next, previous, up +@section Input and Output Functions +@cindex Integer input and output functions +@cindex Input functions +@cindex Output functions +@cindex I/O functions + +Functions that perform input from a stdio stream, and functions that output to +a stdio stream, of @code{mpz} numbers. Passing a @code{NULL} pointer for a +@var{stream} argument to any of these functions will make them read from +@code{stdin} and write to @code{stdout}, respectively. + +When using any of these functions, it is a good idea to include @file{stdio.h} +before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes +for these functions. + +See also @ref{Formatted Output} and @ref{Formatted Input}. + +@deftypefun size_t mpz_out_str (FILE *@var{stream}, int @var{base}, const mpz_t @var{op}) +Output @var{op} on stdio stream @var{stream}, as a string of digits in base +@var{base}. The base argument may vary from 2 to 62 or from @minus{}2 to +@minus{}36. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +Return the number of bytes written, or if an error occurred, return 0. +@end deftypefun + +@deftypefun size_t mpz_inp_str (mpz_t @var{rop}, FILE *@var{stream}, int @var{base}) +Input a possibly white-space preceded string in base @var{base} from stdio +stream @var{stream}, and put the read integer in @var{rop}. + +The @var{base} may vary from 2 to 62, or if @var{base} is 0, then the leading +characters are used: @code{0x} and @code{0X} for hexadecimal, @code{0b} and +@code{0B} for binary, @code{0} for octal, or decimal otherwise. + +For bases up to 36, case is ignored; upper-case and lower-case letters have +the same value. For bases 37 to 62, upper-case letters represent the usual +10..35 while lower-case letters represent 36..61. + +Return the number of bytes read, or if an error occurred, return 0. +@end deftypefun + +@deftypefun size_t mpz_out_raw (FILE *@var{stream}, const mpz_t @var{op}) +Output @var{op} on stdio stream @var{stream}, in raw binary format. The +integer is written in a portable format, with 4 bytes of size information, and +that many bytes of limbs. Both the size and the limbs are written in +decreasing significance order (i.e., in big-endian). + +The output can be read with @code{mpz_inp_raw}. + +Return the number of bytes written, or if an error occurred, return 0. + +The output of this can not be read by @code{mpz_inp_raw} from GMP 1, because +of changes necessary for compatibility between 32-bit and 64-bit machines. +@end deftypefun + +@deftypefun size_t mpz_inp_raw (mpz_t @var{rop}, FILE *@var{stream}) +Input from stdio stream @var{stream} in the format written by +@code{mpz_out_raw}, and put the result in @var{rop}. Return the number of +bytes read, or if an error occurred, return 0. + +This routine can read the output from @code{mpz_out_raw} also from GMP 1, in +spite of changes necessary for compatibility between 32-bit and 64-bit +machines. +@end deftypefun + + +@need 2000 +@node Integer Random Numbers, Integer Import and Export, I/O of Integers, Integer Functions +@comment node-name, next, previous, up +@section Random Number Functions +@cindex Integer random number functions +@cindex Random number functions + +The random number functions of GMP come in two groups; older functions +that rely on a global state, and newer functions that accept a state +parameter that is read and modified. Please see the @ref{Random Number +Functions} for more information on how to use and not to use random +number functions. + +@deftypefun void mpz_urandomb (mpz_t @var{rop}, gmp_randstate_t @var{state}, mp_bitcnt_t @var{n}) +Generate a uniformly distributed random integer in the range 0 to +@mm{2@sup{n}-1, 2^@var{n}@minus{}1}, inclusive. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) before +invoking this function. +@end deftypefun + +@deftypefun void mpz_urandomm (mpz_t @var{rop}, gmp_randstate_t @var{state}, const mpz_t @var{n}) +Generate a uniform random integer in the range 0 to @math{@var{n}-1}, +inclusive. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) +before invoking this function. +@end deftypefun + +@deftypefun void mpz_rrandomb (mpz_t @var{rop}, gmp_randstate_t @var{state}, mp_bitcnt_t @var{n}) +Generate a random integer with long strings of zeros and ones in the +binary representation. Useful for testing functions and algorithms, +since this kind of random numbers have proven to be more likely to +trigger corner-case bugs. The random number will be in the range +@mm{2@sup{n-1}, 2^(@var{n}@minus{}1)} to @mm{2@sup{n}-1, +2^@var{n}@minus{}1}, inclusive. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) +before invoking this function. +@end deftypefun + +@deftypefun void mpz_random (mpz_t @var{rop}, mp_size_t @var{max_size}) +Generate a random integer of at most @var{max_size} limbs. The generated +random number doesn't satisfy any particular requirements of randomness. +Negative random numbers are generated when @var{max_size} is negative. + +This function is obsolete. Use @code{mpz_urandomb} or +@code{mpz_urandomm} instead. +@end deftypefun + +@deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size}) +Generate a random integer of at most @var{max_size} limbs, with long strings +of zeros and ones in the binary representation. Useful for testing functions +and algorithms, since this kind of random numbers have proven to be more +likely to trigger corner-case bugs. Negative random numbers are generated +when @var{max_size} is negative. + +This function is obsolete. Use @code{mpz_rrandomb} instead. +@end deftypefun + + +@node Integer Import and Export, Miscellaneous Integer Functions, Integer Random Numbers, Integer Functions +@section Integer Import and Export + +@code{mpz_t} variables can be converted to and from arbitrary words of binary +data with the following functions. + +@deftypefun void mpz_import (mpz_t @var{rop}, size_t @var{count}, int @var{order}, size_t @var{size}, int @var{endian}, size_t @var{nails}, const void *@var{op}) +@cindex Integer import +@cindex Import +Set @var{rop} from an array of word data at @var{op}. + +The parameters specify the format of the data. @var{count} many words are +read, each @var{size} bytes. @var{order} can be 1 for most significant word +first or -1 for least significant first. Within each word @var{endian} can be +1 for most significant byte first, -1 for least significant first, or 0 for +the native endianness of the host CPU@. The most significant @var{nails} bits +of each word are skipped, this can be 0 to use the full words. + +There is no sign taken from the data, @var{rop} will simply be a positive +integer. An application can handle any sign itself, and apply it for instance +with @code{mpz_neg}. + +There are no data alignment restrictions on @var{op}, any address is allowed. + +Here's an example converting an array of @code{unsigned long} data, most +significant element first, and host byte order within each value. + +@example +unsigned long a[20]; +/* Initialize @var{z} and @var{a} */ +mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a); +@end example + +This example assumes the full @code{sizeof} bytes are used for data in the +given type, which is usually true, and certainly true for @code{unsigned long} +everywhere we know of. However on Cray vector systems it may be noted that +@code{short} and @code{int} are always stored in 8 bytes (and with +@code{sizeof} indicating that) but use only 32 or 46 bits. The @var{nails} +feature can account for this, by passing for instance +@code{8*sizeof(int)-INT_BIT}. +@end deftypefun + +@deftypefun {void *} mpz_export (void *@var{rop}, size_t *@var{countp}, int @var{order}, size_t @var{size}, int @var{endian}, size_t @var{nails}, const mpz_t @var{op}) +@cindex Integer export +@cindex Export +Fill @var{rop} with word data from @var{op}. + +The parameters specify the format of the data produced. Each word will be +@var{size} bytes and @var{order} can be 1 for most significant word first or +-1 for least significant first. Within each word @var{endian} can be 1 for +most significant byte first, -1 for least significant first, or 0 for the +native endianness of the host CPU@. The most significant @var{nails} bits of +each word are unused and set to zero, this can be 0 to produce full words. + +The number of words produced is written to @code{*@var{countp}}, or +@var{countp} can be @code{NULL} to discard the count. @var{rop} must have +enough space for the data, or if @var{rop} is @code{NULL} then a result array +of the necessary size is allocated using the current GMP allocation function +(@pxref{Custom Allocation}). In either case the return value is the +destination used, either @var{rop} or the allocated block. + +If @var{op} is non-zero then the most significant word produced will be +non-zero. If @var{op} is zero then the count returned will be zero and +nothing written to @var{rop}. If @var{rop} is @code{NULL} in this case, no +block is allocated, just @code{NULL} is returned. + +The sign of @var{op} is ignored, just the absolute value is exported. An +application can use @code{mpz_sgn} to get the sign and handle it as desired. +(@pxref{Integer Comparisons}) + +There are no data alignment restrictions on @var{rop}, any address is allowed. + +When an application is allocating space itself the required size can be +determined with a calculation like the following. Since @code{mpz_sizeinbase} +always returns at least 1, @code{count} here will be at least one, which +avoids any portability problems with @code{malloc(0)}, though if @code{z} is +zero no space at all is actually needed (or written). + +@example +numb = 8*size - nail; +count = (mpz_sizeinbase (z, 2) + numb-1) / numb; +p = malloc (count * size); +@end example +@end deftypefun + + +@need 2000 +@node Miscellaneous Integer Functions, Integer Special Functions, Integer Import and Export, Integer Functions +@comment node-name, next, previous, up +@section Miscellaneous Functions +@cindex Miscellaneous integer functions +@cindex Integer miscellaneous functions + +@deftypefun int mpz_fits_ulong_p (const mpz_t @var{op}) +@deftypefunx int mpz_fits_slong_p (const mpz_t @var{op}) +@deftypefunx int mpz_fits_uint_p (const mpz_t @var{op}) +@deftypefunx int mpz_fits_sint_p (const mpz_t @var{op}) +@deftypefunx int mpz_fits_ushort_p (const mpz_t @var{op}) +@deftypefunx int mpz_fits_sshort_p (const mpz_t @var{op}) +Return non-zero iff the value of @var{op} fits in an @code{unsigned long int}, +@code{signed long int}, @code{unsigned int}, @code{signed int}, @code{unsigned +short int}, or @code{signed short int}, respectively. Otherwise, return zero. +@end deftypefun + +@deftypefn Macro int mpz_odd_p (const mpz_t @var{op}) +@deftypefnx Macro int mpz_even_p (const mpz_t @var{op}) +Determine whether @var{op} is odd or even, respectively. Return non-zero if +yes, zero if no. These macros evaluate their argument more than once. +@end deftypefn + +@deftypefun size_t mpz_sizeinbase (const mpz_t @var{op}, int @var{base}) +@cindex Size in digits +@cindex Digits in an integer +Return the size of @var{op} measured in number of digits in the given +@var{base}. @var{base} can vary from 2 to 62. The sign of @var{op} is +ignored, just the absolute value is used. The result will be either exact or +1 too big. If @var{base} is a power of 2, the result is always exact. If +@var{op} is zero the return value is always 1. + +This function can be used to determine the space required when converting +@var{op} to a string. The right amount of allocation is normally two more +than the value returned by @code{mpz_sizeinbase}, one extra for a minus sign +and one for the null-terminator. + +@cindex Most significant bit +It will be noted that @code{mpz_sizeinbase(@var{op},2)} can be used to locate +the most significant 1 bit in @var{op}, counting from 1. (Unlike the bitwise +functions which start from 0, @xref{Integer Logic and Bit Fiddling,, Logical +and Bit Manipulation Functions}.) +@end deftypefun + + +@node Integer Special Functions, , Miscellaneous Integer Functions, Integer Functions +@section Special Functions +@cindex Special integer functions +@cindex Integer special functions + +The functions in this section are for various special purposes. Most +applications will not need them. + +@deftypefun void mpz_array_init (mpz_t @var{integer_array}, mp_size_t @var{array_size}, @w{mp_size_t @var{fixed_num_bits}}) +@strong{This is an obsolete function. Do not use it.} +@end deftypefun + +@deftypefun {void *} _mpz_realloc (mpz_t @var{integer}, mp_size_t @var{new_alloc}) +Change the space for @var{integer} to @var{new_alloc} limbs. The value in +@var{integer} is preserved if it fits, or is set to 0 if not. The return +value is not useful to applications and should be ignored. + +@code{mpz_realloc2} is the preferred way to accomplish allocation changes like +this. @code{mpz_realloc2} and @code{_mpz_realloc} are the same except that +@code{_mpz_realloc} takes its size in limbs. +@end deftypefun + +@deftypefun mp_limb_t mpz_getlimbn (const mpz_t @var{op}, mp_size_t @var{n}) +Return limb number @var{n} from @var{op}. The sign of @var{op} is ignored, +just the absolute value is used. The least significant limb is number 0. + +@code{mpz_size} can be used to find how many limbs make up @var{op}. +@code{mpz_getlimbn} returns zero if @var{n} is outside the range 0 to +@code{mpz_size(@var{op})-1}. +@end deftypefun + +@deftypefun size_t mpz_size (const mpz_t @var{op}) +Return the size of @var{op} measured in number of limbs. If @var{op} is zero, +the returned value will be zero. +@c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.) +@end deftypefun + +@deftypefun {const mp_limb_t *} mpz_limbs_read (const mpz_t @var{x}) +Return a pointer to the limb array representing the absolute value of @var{x}. +The size of the array is @code{mpz_size(@var{x})}. Intended for read access +only. +@end deftypefun + +@deftypefun {mp_limb_t *} mpz_limbs_write (mpz_t @var{x}, mp_size_t @var{n}) +@deftypefunx {mp_limb_t *} mpz_limbs_modify (mpz_t @var{x}, mp_size_t @var{n}) +Return a pointer to the limb array, intended for write access. The array is +reallocated as needed, to make room for @var{n} limbs. Requires @math{@var{n} +> 0}. The @code{mpz_limbs_modify} function returns an array that holds the old +absolute value of @var{x}, while @code{mpz_limbs_write} may destroy the old +value and return an array with unspecified contents. +@end deftypefun + +@deftypefun void mpz_limbs_finish (mpz_t @var{x}, mp_size_t @var{s}) +Updates the internal size field of @var{x}. Used after writing to the limb +array pointer returned by @code{mpz_limbs_write} or @code{mpz_limbs_modify} is +completed. The array should contain @math{@GMPabs{@var{s}}} valid limbs, +representing the new absolute value for @var{x}, and the sign of @var{x} is +taken from the sign of @var{s}. This function never reallocates @var{x}, so +the limb pointer remains valid. +@end deftypefun + +@c FIXME: Some more useful and less silly example? +@example +void foo (mpz_t x) +@{ + mp_size_t n, i; + mp_limb_t *xp; + + n = mpz_size (x); + xp = mpz_limbs_modify (x, 2*n); + for (i = 0; i < n; i++) + xp[n+i] = xp[n-1-i]; + mpz_limbs_finish (x, mpz_sgn (x) < 0 ? - 2*n : 2*n); +@} +@end example + +@deftypefun mpz_srcptr mpz_roinit_n (mpz_t @var{x}, const mp_limb_t *@var{xp}, mp_size_t @var{xs}) +Special initialization of @var{x}, using the given limb array and size. +@var{x} should be treated as read-only: it can be passed safely as input to +any mpz function, but not as an output. The array @var{xp} must point to at +least a readable limb, its size is +@math{@GMPabs{@var{xs}}}, and the sign of @var{x} is the sign of @var{xs}. For +convenience, the function returns @var{x}, but cast to a const pointer type. +@end deftypefun + +@example +void foo (mpz_t x) +@{ + static const mp_limb_t y[3] = @{ 0x1, 0x2, 0x3 @}; + mpz_t tmp; + mpz_add (x, x, mpz_roinit_n (tmp, y, 3)); +@} +@end example + +@deftypefn Macro mpz_t MPZ_ROINIT_N (mp_limb_t *@var{xp}, mp_size_t @var{xs}) +This macro expands to an initializer which can be assigned to an mpz_t +variable. The limb array @var{xp} must point to at least a readable limb, +moreover, unlike the @code{mpz_roinit_n} function, the array must be +normalized: if @var{xs} is non-zero, then +@code{@var{xp}[@math{@GMPabs{@var{xs}}-1}]} must be non-zero. Intended +primarily for constant values. Using it for non-constant values requires a C +compiler supporting C99. +@end deftypefn + +@example +void foo (mpz_t x) +@{ + static const mp_limb_t ya[3] = @{ 0x1, 0x2, 0x3 @}; + static const mpz_t y = MPZ_ROINIT_N ((mp_limb_t *) ya, 3); + + mpz_add (x, x, y); +@} +@end example + + +@node Rational Number Functions, Floating-point Functions, Integer Functions, Top +@comment node-name, next, previous, up +@chapter Rational Number Functions +@cindex Rational number functions + +This chapter describes the GMP functions for performing arithmetic on rational +numbers. These functions start with the prefix @code{mpq_}. + +Rational numbers are stored in objects of type @code{mpq_t}. + +All rational arithmetic functions assume operands have a canonical form, and +canonicalize their result. The canonical form means that the denominator and +the numerator have no common factors, and that the denominator is positive. +Zero has the unique representation 0/1. + +Pure assignment functions do not canonicalize the assigned variable. It is +the responsibility of the user to canonicalize the assigned variable before +any arithmetic operations are performed on that variable. + +@deftypefun void mpq_canonicalize (mpq_t @var{op}) +Remove any factors that are common to the numerator and denominator of +@var{op}, and make the denominator positive. +@end deftypefun + +@menu +* Initializing Rationals:: +* Rational Conversions:: +* Rational Arithmetic:: +* Comparing Rationals:: +* Applying Integer Functions:: +* I/O of Rationals:: +@end menu + +@node Initializing Rationals, Rational Conversions, Rational Number Functions, Rational Number Functions +@comment node-name, next, previous, up +@section Initialization and Assignment Functions +@cindex Rational assignment functions +@cindex Assignment functions +@cindex Rational initialization functions +@cindex Initialization functions + +@deftypefun void mpq_init (mpq_t @var{x}) +Initialize @var{x} and set it to 0/1. Each variable should normally only be +initialized once, or at least cleared out (using the function @code{mpq_clear}) +between each initialization. +@end deftypefun + +@deftypefun void mpq_inits (mpq_t @var{x}, ...) +Initialize a NULL-terminated list of @code{mpq_t} variables, and set their +values to 0/1. +@end deftypefun + +@deftypefun void mpq_clear (mpq_t @var{x}) +Free the space occupied by @var{x}. Make sure to call this function for all +@code{mpq_t} variables when you are done with them. +@end deftypefun + +@deftypefun void mpq_clears (mpq_t @var{x}, ...) +Free the space occupied by a NULL-terminated list of @code{mpq_t} variables. +@end deftypefun + +@deftypefun void mpq_set (mpq_t @var{rop}, const mpq_t @var{op}) +@deftypefunx void mpq_set_z (mpq_t @var{rop}, const mpz_t @var{op}) +Assign @var{rop} from @var{op}. +@end deftypefun + +@deftypefun void mpq_set_ui (mpq_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}) +@deftypefunx void mpq_set_si (mpq_t @var{rop}, signed long int @var{op1}, unsigned long int @var{op2}) +Set the value of @var{rop} to @var{op1}/@var{op2}. Note that if @var{op1} and +@var{op2} have common factors, @var{rop} has to be passed to +@code{mpq_canonicalize} before any operations are performed on @var{rop}. +@end deftypefun + +@deftypefun int mpq_set_str (mpq_t @var{rop}, const char *@var{str}, int @var{base}) +Set @var{rop} from a null-terminated string @var{str} in the given @var{base}. + +The string can be an integer like ``41'' or a fraction like ``41/152''. The +fraction must be in canonical form (@pxref{Rational Number Functions}), or if +not then @code{mpq_canonicalize} must be called. + +The numerator and optional denominator are parsed the same as in +@code{mpz_set_str} (@pxref{Assigning Integers}). White space is allowed in +the string, and is simply ignored. The @var{base} can vary from 2 to 62, or +if @var{base} is 0 then the leading characters are used: @code{0x} or @code{0X} for hex, +@code{0b} or @code{0B} for binary, +@code{0} for octal, or decimal otherwise. Note that this is done separately +for the numerator and denominator, so for instance @code{0xEF/100} is 239/100, +whereas @code{0xEF/0x100} is 239/256. + +The return value is 0 if the entire string is a valid number, or @minus{}1 if +not. +@end deftypefun + +@deftypefun void mpq_swap (mpq_t @var{rop1}, mpq_t @var{rop2}) +Swap the values @var{rop1} and @var{rop2} efficiently. +@end deftypefun + + +@need 2000 +@node Rational Conversions, Rational Arithmetic, Initializing Rationals, Rational Number Functions +@comment node-name, next, previous, up +@section Conversion Functions +@cindex Rational conversion functions +@cindex Conversion functions + +@deftypefun double mpq_get_d (const mpq_t @var{op}) +Convert @var{op} to a @code{double}, truncating if necessary (i.e.@: rounding +towards zero). + +If the exponent from the conversion is too big or too small to fit a +@code{double} then the result is system dependent. For too big an infinity is +returned when available. For too small @math{0.0} is normally returned. +Hardware overflow, underflow and denorm traps may or may not occur. +@end deftypefun + +@deftypefun void mpq_set_d (mpq_t @var{rop}, double @var{op}) +@deftypefunx void mpq_set_f (mpq_t @var{rop}, const mpf_t @var{op}) +Set @var{rop} to the value of @var{op}. There is no rounding, this conversion +is exact. +@end deftypefun + +@deftypefun {char *} mpq_get_str (char *@var{str}, int @var{base}, const mpq_t @var{op}) +Convert @var{op} to a string of digits in base @var{base}. The base argument +may vary from 2 to 62 or from @minus{}2 to @minus{}36. The string will be of +the form @samp{num/den}, or if the denominator is 1 then just @samp{num}. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +If @var{str} is @code{NULL}, the result string is allocated using the current +allocation function (@pxref{Custom Allocation}). The block will be +@code{strlen(str)+1} bytes, that being exactly enough for the string and +null-terminator. + +If @var{str} is not @code{NULL}, it should point to a block of storage large +enough for the result, that being + +@example +mpz_sizeinbase (mpq_numref(@var{op}), @var{base}) ++ mpz_sizeinbase (mpq_denref(@var{op}), @var{base}) + 3 +@end example + +The three extra bytes are for a possible minus sign, possible slash, and the +null-terminator. + +A pointer to the result string is returned, being either the allocated block, +or the given @var{str}. +@end deftypefun + + +@node Rational Arithmetic, Comparing Rationals, Rational Conversions, Rational Number Functions +@comment node-name, next, previous, up +@section Arithmetic Functions +@cindex Rational arithmetic functions +@cindex Arithmetic functions + +@deftypefun void mpq_add (mpq_t @var{sum}, const mpq_t @var{addend1}, const mpq_t @var{addend2}) +Set @var{sum} to @var{addend1} + @var{addend2}. +@end deftypefun + +@deftypefun void mpq_sub (mpq_t @var{difference}, const mpq_t @var{minuend}, const mpq_t @var{subtrahend}) +Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}. +@end deftypefun + +@deftypefun void mpq_mul (mpq_t @var{product}, const mpq_t @var{multiplier}, const mpq_t @var{multiplicand}) +Set @var{product} to @math{@var{multiplier} @GMPtimes{} @var{multiplicand}}. +@end deftypefun + +@deftypefun void mpq_mul_2exp (mpq_t @var{rop}, const mpq_t @var{op1}, mp_bitcnt_t @var{op2}) +Set @var{rop} to @m{@var{op1} \times 2^{op2}, @var{op1} times 2 raised to +@var{op2}}. +@end deftypefun + +@deftypefun void mpq_div (mpq_t @var{quotient}, const mpq_t @var{dividend}, const mpq_t @var{divisor}) +@cindex Division functions +Set @var{quotient} to @var{dividend}/@var{divisor}. +@end deftypefun + +@deftypefun void mpq_div_2exp (mpq_t @var{rop}, const mpq_t @var{op1}, mp_bitcnt_t @var{op2}) +Set @var{rop} to @m{@var{op1}/2^{op2}, @var{op1} divided by 2 raised to +@var{op2}}. +@end deftypefun + +@deftypefun void mpq_neg (mpq_t @var{negated_operand}, const mpq_t @var{operand}) +Set @var{negated_operand} to @minus{}@var{operand}. +@end deftypefun + +@deftypefun void mpq_abs (mpq_t @var{rop}, const mpq_t @var{op}) +Set @var{rop} to the absolute value of @var{op}. +@end deftypefun + +@deftypefun void mpq_inv (mpq_t @var{inverted_number}, const mpq_t @var{number}) +Set @var{inverted_number} to 1/@var{number}. If the new denominator is +zero, this routine will divide by zero. +@end deftypefun + +@node Comparing Rationals, Applying Integer Functions, Rational Arithmetic, Rational Number Functions +@comment node-name, next, previous, up +@section Comparison Functions +@cindex Rational comparison functions +@cindex Comparison functions + +@deftypefun int mpq_cmp (const mpq_t @var{op1}, const mpq_t @var{op2}) +@deftypefunx int mpq_cmp_z (const mpq_t @var{op1}, const mpz_t @var{op2}) +Compare @var{op1} and @var{op2}. Return a positive value if @math{@var{op1} > +@var{op2}}, zero if @math{@var{op1} = @var{op2}}, and a negative value if +@math{@var{op1} < @var{op2}}. + +To determine if two rationals are equal, @code{mpq_equal} is faster than +@code{mpq_cmp}. +@end deftypefun + +@deftypefn Macro int mpq_cmp_ui (const mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2}) +@deftypefnx Macro int mpq_cmp_si (const mpq_t @var{op1}, long int @var{num2}, unsigned long int @var{den2}) +Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if +@math{@var{op1} > @var{num2}/@var{den2}}, zero if @math{@var{op1} = +@var{num2}/@var{den2}}, and a negative value if @math{@var{op1} < +@var{num2}/@var{den2}}. + +@var{num2} and @var{den2} are allowed to have common factors. + +These functions are implemented as macros and evaluate their arguments +multiple times. +@end deftypefn + +@deftypefn Macro int mpq_sgn (const mpq_t @var{op}) +@cindex Sign tests +@cindex Rational sign tests +Return @math{+1} if @math{@var{op} > 0}, 0 if @math{@var{op} = 0}, and +@math{-1} if @math{@var{op} < 0}. + +This function is actually implemented as a macro. It evaluates its +argument multiple times. +@end deftypefn + +@deftypefun int mpq_equal (const mpq_t @var{op1}, const mpq_t @var{op2}) +Return non-zero if @var{op1} and @var{op2} are equal, zero if they are +non-equal. Although @code{mpq_cmp} can be used for the same purpose, this +function is much faster. +@end deftypefun + +@node Applying Integer Functions, I/O of Rationals, Comparing Rationals, Rational Number Functions +@comment node-name, next, previous, up +@section Applying Integer Functions to Rationals +@cindex Rational numerator and denominator +@cindex Numerator and denominator + +The set of @code{mpq} functions is quite small. In particular, there are few +functions for either input or output. The following functions give direct +access to the numerator and denominator of an @code{mpq_t}. + +Note that if an assignment to the numerator and/or denominator could take an +@code{mpq_t} out of the canonical form described at the start of this chapter +(@pxref{Rational Number Functions}) then @code{mpq_canonicalize} must be +called before any other @code{mpq} functions are applied to that @code{mpq_t}. + +@deftypefn Macro mpz_ptr mpq_numref (const mpq_t @var{op}) +@deftypefnx Macro mpz_ptr mpq_denref (const mpq_t @var{op}) +Return a reference to the numerator and denominator of @var{op}, respectively. +The @code{mpz} functions can be used on the result of these macros. Such +calls may modify the numerator or denominator. However, care +should be taken so that @var{op} remains in canonical form prior to a +possible later call to an @code{mpq} function. +@end deftypefn + +@deftypefun void mpq_get_num (mpz_t @var{numerator}, const mpq_t @var{rational}) +@deftypefunx void mpq_get_den (mpz_t @var{denominator}, const mpq_t @var{rational}) +@deftypefunx void mpq_set_num (mpq_t @var{rational}, const mpz_t @var{numerator}) +@deftypefunx void mpq_set_den (mpq_t @var{rational}, const mpz_t @var{denominator}) +Get or set the numerator or denominator of a rational. These functions are +equivalent to calling @code{mpz_set} with an appropriate @code{mpq_numref} or +@code{mpq_denref}. Direct use of @code{mpq_numref} or @code{mpq_denref} is +recommended instead of these functions. +@end deftypefun + + +@need 2000 +@node I/O of Rationals, , Applying Integer Functions, Rational Number Functions +@comment node-name, next, previous, up +@section Input and Output Functions +@cindex Rational input and output functions +@cindex Input functions +@cindex Output functions +@cindex I/O functions + +Functions that perform input from a stdio stream, and functions that output to +a stdio stream, of @code{mpq} numbers. Passing a @code{NULL} pointer for a +@var{stream} argument to any of these functions will make them read from +@code{stdin} and write to @code{stdout}, respectively. + +When using any of these functions, it is a good idea to include @file{stdio.h} +before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes +for these functions. + +See also @ref{Formatted Output} and @ref{Formatted Input}. + +@deftypefun size_t mpq_out_str (FILE *@var{stream}, int @var{base}, const mpq_t @var{op}) +Output @var{op} on stdio stream @var{stream}, as a string of digits in base +@var{base}. The base argument may vary from 2 to 62 or from @minus{}2 to +@minus{}36. Output is in the form +@samp{num/den} or if the denominator is 1 then just @samp{num}. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +Return the number of bytes written, or if an error occurred, return 0. +@end deftypefun + +@deftypefun size_t mpq_inp_str (mpq_t @var{rop}, FILE *@var{stream}, int @var{base}) +Read a string of digits from @var{stream} and convert them to a rational in +@var{rop}. Any initial white-space characters are read and discarded. Return +the number of characters read (including white space), or 0 if a rational +could not be read. + +The input can be a fraction like @samp{17/63} or just an integer like +@samp{123}. Reading stops at the first character not in this form, and white +space is not permitted within the string. If the input might not be in +canonical form, then @code{mpq_canonicalize} must be called (@pxref{Rational +Number Functions}). + +The @var{base} can be between 2 and 62, or can be 0 in which case the leading +characters of the string determine the base, @samp{0x} or @samp{0X} for +hexadecimal, @code{0b} and @code{0B} for binary, @samp{0} for octal, or +decimal otherwise. The leading characters +are examined separately for the numerator and denominator of a fraction, so +for instance @samp{0x10/11} is @math{16/11}, whereas @samp{0x10/0x11} is +@math{16/17}. +@end deftypefun + + +@node Floating-point Functions, Low-level Functions, Rational Number Functions, Top +@comment node-name, next, previous, up +@chapter Floating-point Functions +@cindex Floating-point functions +@cindex Float functions +@cindex User-defined precision +@cindex Precision of floats + +GMP floating point numbers are stored in objects of type @code{mpf_t} and +functions operating on them have an @code{mpf_} prefix. + +The mantissa of each float has a user-selectable precision, in practice only +limited by available memory. Each variable has its own precision, and that can +be increased or decreased at any time. This selectable precision is a minimum +value, GMP rounds it up to a whole limb. + +The accuracy of a calculation is determined by the priorly set precision of the +destination variable and the numeric values of the input variables. Input +variables' set precisions do not affect calculations (except indirectly as +their values might have been affected when they were assigned). + +The exponent of each float has fixed precision, one machine word on most +systems. In the current implementation the exponent is a count of limbs, so +for example on a 32-bit system this means a range of roughly +@math{2^@W{-68719476768}} to @math{2^@W{68719476736}}, or on a 64-bit system +this will be much greater. Note however that @code{mpf_get_str} can only +return an exponent which fits an @code{mp_exp_t} and currently +@code{mpf_set_str} doesn't accept exponents bigger than a @code{long}. + +Each variable keeps track of the mantissa data actually in use. This means +that if a float is exactly represented in only a few bits then only those bits +will be used in a calculation, even if the variable's selected precision is +high. This is a performance optimization; it does not affect the numeric +results. + +Internally, GMP sometimes calculates with higher precision than that of the +destination variable in order to limit errors. Final results are always +truncated to the destination variable's precision. + +The mantissa is stored in binary. One consequence of this is that decimal +fractions like @math{0.1} cannot be represented exactly. The same is true of +plain IEEE @code{double} floats. This makes both highly unsuitable for +calculations involving money or other values that should be exact decimal +fractions. (Suitably scaled integers, or perhaps rationals, are better +choices.) + +The @code{mpf} functions and variables have no special notion of infinity or +not-a-number, and applications must take care not to overflow the exponent or +results will be unpredictable. + +Note that the @code{mpf} functions are @emph{not} intended as a smooth +extension to IEEE P754 arithmetic. In particular results obtained on one +computer often differ from the results on a computer with a different word +size. + +New projects should consider using the GMP extension library MPFR +(@url{https://www.mpfr.org/}) instead. MPFR provides well-defined precision and +accurate rounding, and thereby naturally extends IEEE P754. + +@menu +* Initializing Floats:: +* Assigning Floats:: +* Simultaneous Float Init & Assign:: +* Converting Floats:: +* Float Arithmetic:: +* Float Comparison:: +* I/O of Floats:: +* Miscellaneous Float Functions:: +@end menu + +@node Initializing Floats, Assigning Floats, Floating-point Functions, Floating-point Functions +@comment node-name, next, previous, up +@section Initialization Functions +@cindex Float initialization functions +@cindex Initialization functions + +@deftypefun void mpf_set_default_prec (mp_bitcnt_t @var{prec}) +Set the default precision to be @strong{at least} @var{prec} bits. All +subsequent calls to @code{mpf_init} will use this precision, but previously +initialized variables are unaffected. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpf_get_default_prec (void) +Return the default precision actually used. +@end deftypefun + +An @code{mpf_t} object must be initialized before storing the first value in +it. The functions @code{mpf_init} and @code{mpf_init2} are used for that +purpose. + +@deftypefun void mpf_init (mpf_t @var{x}) +Initialize @var{x} to 0. Normally, a variable should be initialized once only +or at least be cleared, using @code{mpf_clear}, between initializations. The +precision of @var{x} is undefined unless a default precision has already been +established by a call to @code{mpf_set_default_prec}. +@end deftypefun + +@deftypefun void mpf_init2 (mpf_t @var{x}, mp_bitcnt_t @var{prec}) +Initialize @var{x} to 0 and set its precision to be @strong{at least} +@var{prec} bits. Normally, a variable should be initialized once only or at +least be cleared, using @code{mpf_clear}, between initializations. +@end deftypefun + +@deftypefun void mpf_inits (mpf_t @var{x}, ...) +Initialize a NULL-terminated list of @code{mpf_t} variables, and set their +values to 0. The precision of the initialized variables is undefined unless a +default precision has already been established by a call to +@code{mpf_set_default_prec}. +@end deftypefun + +@deftypefun void mpf_clear (mpf_t @var{x}) +Free the space occupied by @var{x}. Make sure to call this function for all +@code{mpf_t} variables when you are done with them. +@end deftypefun + +@deftypefun void mpf_clears (mpf_t @var{x}, ...) +Free the space occupied by a NULL-terminated list of @code{mpf_t} variables. +@end deftypefun + +@need 2000 +Here is an example on how to initialize floating-point variables: +@example +@{ + mpf_t x, y; + mpf_init (x); /* use default precision */ + mpf_init2 (y, 256); /* precision @emph{at least} 256 bits */ + @dots{} + /* Unless the program is about to exit, do ... */ + mpf_clear (x); + mpf_clear (y); +@} +@end example + +The following three functions are useful for changing the precision during a +calculation. A typical use would be for adjusting the precision gradually in +iterative algorithms like Newton-Raphson, making the computation precision +closely match the actual accurate part of the numbers. + +@deftypefun {mp_bitcnt_t} mpf_get_prec (const mpf_t @var{op}) +Return the current precision of @var{op}, in bits. +@end deftypefun + +@deftypefun void mpf_set_prec (mpf_t @var{rop}, mp_bitcnt_t @var{prec}) +Set the precision of @var{rop} to be @strong{at least} @var{prec} bits. The +value in @var{rop} will be truncated to the new precision. + +This function requires a call to @code{realloc}, and so should not be used in +a tight loop. +@end deftypefun + +@deftypefun void mpf_set_prec_raw (mpf_t @var{rop}, mp_bitcnt_t @var{prec}) +Set the precision of @var{rop} to be @strong{at least} @var{prec} bits, +without changing the memory allocated. + +@var{prec} must be no more than the allocated precision for @var{rop}, that +being the precision when @var{rop} was initialized, or in the most recent +@code{mpf_set_prec}. + +The value in @var{rop} is unchanged, and in particular if it had a higher +precision than @var{prec} it will retain that higher precision. New values +written to @var{rop} will use the new @var{prec}. + +Before calling @code{mpf_clear} or the full @code{mpf_set_prec}, another +@code{mpf_set_prec_raw} call must be made to restore @var{rop} to its original +allocated precision. Failing to do so will have unpredictable results. + +@code{mpf_get_prec} can be used before @code{mpf_set_prec_raw} to get the +original allocated precision. After @code{mpf_set_prec_raw} it reflects the +@var{prec} value set. + +@code{mpf_set_prec_raw} is an efficient way to use an @code{mpf_t} variable at +different precisions during a calculation, perhaps to gradually increase +precision in an iteration, or just to use various different precisions for +different purposes during a calculation. +@end deftypefun + + +@need 2000 +@node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions +@comment node-name, next, previous, up +@section Assignment Functions +@cindex Float assignment functions +@cindex Assignment functions + +These functions assign new values to already initialized floats +(@pxref{Initializing Floats}). + +@deftypefun void mpf_set (mpf_t @var{rop}, const mpf_t @var{op}) +@deftypefunx void mpf_set_ui (mpf_t @var{rop}, unsigned long int @var{op}) +@deftypefunx void mpf_set_si (mpf_t @var{rop}, signed long int @var{op}) +@deftypefunx void mpf_set_d (mpf_t @var{rop}, double @var{op}) +@deftypefunx void mpf_set_z (mpf_t @var{rop}, const mpz_t @var{op}) +@deftypefunx void mpf_set_q (mpf_t @var{rop}, const mpq_t @var{op}) +Set the value of @var{rop} from @var{op}. +@end deftypefun + +@deftypefun int mpf_set_str (mpf_t @var{rop}, const char *@var{str}, int @var{base}) +Set the value of @var{rop} from the string in @var{str}. The string is of the +form @samp{M@@N} or, if the base is 10 or less, alternatively @samp{MeN}. +@samp{M} is the mantissa and @samp{N} is the exponent. The mantissa is always +in the specified base. The exponent is either in the specified base or, if +@var{base} is negative, in decimal. The decimal point expected is taken from +the current locale, on systems providing @code{localeconv}. + +The argument @var{base} may be in the ranges 2 to 62, or @minus{}62 to +@minus{}2. Negative values are used to specify that the exponent is in +decimal. + +For bases up to 36, case is ignored; upper-case and lower-case letters have +the same value; for bases 37 to 62, upper-case letters represent the usual +10..35 while lower-case letters represent 36..61. + +Unlike the corresponding @code{mpz} function, the base will not be determined +from the leading characters of the string if @var{base} is 0. This is so that +numbers like @samp{0.23} are not interpreted as octal. + +White space is allowed in the string, and is simply ignored. [This is not +really true; white-space is ignored in the beginning of the string and within +the mantissa, but not in other places, such as after a minus sign or in the +exponent. We are considering changing the definition of this function, making +it fail when there is any white-space in the input, since that makes a lot of +sense. Please tell us your opinion about this change. Do you really want it +to accept @nicode{"3 14"} as meaning 314 as it does now?] + +This function returns 0 if the entire string is a valid number in base +@var{base}. Otherwise it returns @minus{}1. +@end deftypefun + +@deftypefun void mpf_swap (mpf_t @var{rop1}, mpf_t @var{rop2}) +Swap @var{rop1} and @var{rop2} efficiently. Both the values and the +precisions of the two variables are swapped. +@end deftypefun + + +@node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions +@comment node-name, next, previous, up +@section Combined Initialization and Assignment Functions +@cindex Float assignment functions +@cindex Assignment functions +@cindex Float initialization functions +@cindex Initialization functions + +For convenience, GMP provides a parallel series of initialize-and-set functions +which initialize the output and then store the value there. These functions' +names have the form @code{mpf_init_set@dots{}} + +Once the float has been initialized by any of the @code{mpf_init_set@dots{}} +functions, it can be used as the source or destination operand for the ordinary +float functions. Don't use an initialize-and-set function on a variable +already initialized! + +@deftypefun void mpf_init_set (mpf_t @var{rop}, const mpf_t @var{op}) +@deftypefunx void mpf_init_set_ui (mpf_t @var{rop}, unsigned long int @var{op}) +@deftypefunx void mpf_init_set_si (mpf_t @var{rop}, signed long int @var{op}) +@deftypefunx void mpf_init_set_d (mpf_t @var{rop}, double @var{op}) +Initialize @var{rop} and set its value from @var{op}. + +The precision of @var{rop} will be taken from the active default precision, as +set by @code{mpf_set_default_prec}. +@end deftypefun + +@deftypefun int mpf_init_set_str (mpf_t @var{rop}, const char *@var{str}, int @var{base}) +Initialize @var{rop} and set its value from the string in @var{str}. See +@code{mpf_set_str} above for details on the assignment operation. + +Note that @var{rop} is initialized even if an error occurs. (I.e., you have to +call @code{mpf_clear} for it.) + +The precision of @var{rop} will be taken from the active default precision, as +set by @code{mpf_set_default_prec}. +@end deftypefun + + +@node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions +@comment node-name, next, previous, up +@section Conversion Functions +@cindex Float conversion functions +@cindex Conversion functions + +@deftypefun double mpf_get_d (const mpf_t @var{op}) +Convert @var{op} to a @code{double}, truncating if necessary (i.e.@: rounding +towards zero). + +If the exponent in @var{op} is too big or too small to fit a @code{double} +then the result is system dependent. For too big an infinity is returned when +available. For too small @math{0.0} is normally returned. Hardware overflow, +underflow and denorm traps may or may not occur. +@end deftypefun + +@deftypefun double mpf_get_d_2exp (signed long int *@var{exp}, const mpf_t @var{op}) +Convert @var{op} to a @code{double}, truncating if necessary (i.e.@: rounding +towards zero), and with an exponent returned separately. + +The return value is in the range @math{0.5@le{}@GMPabs{@var{d}}<1} and the +exponent is stored to @code{*@var{exp}}. @m{@var{d} \times 2^{exp}, +@var{d} * 2^@var{exp}} is the (truncated) @var{op} value. If @var{op} is zero, +the return is @math{0.0} and 0 is stored to @code{*@var{exp}}. + +@cindex @code{frexp} +This is similar to the standard C @code{frexp} function (@pxref{Normalization +Functions,,, libc, The GNU C Library Reference Manual}). +@end deftypefun + +@deftypefun long mpf_get_si (const mpf_t @var{op}) +@deftypefunx {unsigned long} mpf_get_ui (const mpf_t @var{op}) +Convert @var{op} to a @code{long} or @code{unsigned long}, truncating any +fraction part. If @var{op} is too big for the return type, the result is +undefined. + +See also @code{mpf_fits_slong_p} and @code{mpf_fits_ulong_p} +(@pxref{Miscellaneous Float Functions}). +@end deftypefun + +@deftypefun {char *} mpf_get_str (char *@var{str}, mp_exp_t *@var{expptr}, int @var{base}, size_t @var{n_digits}, const mpf_t @var{op}) +Convert @var{op} to a string of digits in base @var{base}. The base argument +may vary from 2 to 62 or from @minus{}2 to @minus{}36. Up to @var{n_digits} +digits will be generated. Trailing zeros are not returned. No more digits +than can be accurately represented by @var{op} are ever generated. If +@var{n_digits} is 0 then that accurate maximum number of digits are generated. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +If @var{str} is @code{NULL}, the result string is allocated using the current +allocation function (@pxref{Custom Allocation}). The block will be +@code{strlen(str)+1} bytes, that being exactly enough for the string and +null-terminator. + +If @var{str} is not @code{NULL}, it should point to a block of +@math{@var{n_digits} + 2} bytes, that being enough for the mantissa, a +possible minus sign, and a null-terminator. When @var{n_digits} is 0 to get +all significant digits, an application won't be able to know the space +required, and @var{str} should be @code{NULL} in that case. + +The generated string is a fraction, with an implicit radix point immediately +to the left of the first digit. The applicable exponent is written through +the @var{expptr} pointer. For example, the number 3.1416 would be returned as +string @nicode{"31416"} and exponent 1. + +When @var{op} is zero, an empty string is produced and the exponent returned +is 0. + +A pointer to the result string is returned, being either the allocated block +or the given @var{str}. +@end deftypefun + + +@node Float Arithmetic, Float Comparison, Converting Floats, Floating-point Functions +@comment node-name, next, previous, up +@section Arithmetic Functions +@cindex Float arithmetic functions +@cindex Arithmetic functions + +@deftypefun void mpf_add (mpf_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_add_ui (mpf_t @var{rop}, const mpf_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{op1} + @var{op2}}. +@end deftypefun + +@deftypefun void mpf_sub (mpf_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_ui_sub (mpf_t @var{rop}, unsigned long int @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_sub_ui (mpf_t @var{rop}, const mpf_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @var{op1} @minus{} @var{op2}. +@end deftypefun + +@deftypefun void mpf_mul (mpf_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_mul_ui (mpf_t @var{rop}, const mpf_t @var{op1}, unsigned long int @var{op2}) +Set @var{rop} to @math{@var{op1} @GMPtimes{} @var{op2}}. +@end deftypefun + +Division is undefined if the divisor is zero, and passing a zero divisor to the +divide functions will make these functions intentionally divide by zero. This +lets the user handle arithmetic exceptions in these functions in the same +manner as other arithmetic exceptions. + +@deftypefun void mpf_div (mpf_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_ui_div (mpf_t @var{rop}, unsigned long int @var{op1}, const mpf_t @var{op2}) +@deftypefunx void mpf_div_ui (mpf_t @var{rop}, const mpf_t @var{op1}, unsigned long int @var{op2}) +@cindex Division functions +Set @var{rop} to @var{op1}/@var{op2}. +@end deftypefun + +@deftypefun void mpf_sqrt (mpf_t @var{rop}, const mpf_t @var{op}) +@deftypefunx void mpf_sqrt_ui (mpf_t @var{rop}, unsigned long int @var{op}) +@cindex Root extraction functions +Set @var{rop} to @m{\sqrt{@var{op}}, the square root of @var{op}}. +@end deftypefun + +@deftypefun void mpf_pow_ui (mpf_t @var{rop}, const mpf_t @var{op1}, unsigned long int @var{op2}) +@cindex Exponentiation functions +@cindex Powering functions +Set @var{rop} to @m{@var{op1}^{op2}, @var{op1} raised to the power @var{op2}}. +@end deftypefun + +@deftypefun void mpf_neg (mpf_t @var{rop}, const mpf_t @var{op}) +Set @var{rop} to @minus{}@var{op}. +@end deftypefun + +@deftypefun void mpf_abs (mpf_t @var{rop}, const mpf_t @var{op}) +Set @var{rop} to the absolute value of @var{op}. +@end deftypefun + +@deftypefun void mpf_mul_2exp (mpf_t @var{rop}, const mpf_t @var{op1}, mp_bitcnt_t @var{op2}) +Set @var{rop} to @m{@var{op1} \times 2^{op2}, @var{op1} times 2 raised to +@var{op2}}. +@end deftypefun + +@deftypefun void mpf_div_2exp (mpf_t @var{rop}, const mpf_t @var{op1}, mp_bitcnt_t @var{op2}) +Set @var{rop} to @m{@var{op1}/2^{op2}, @var{op1} divided by 2 raised to +@var{op2}}. +@end deftypefun + +@node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions +@comment node-name, next, previous, up +@section Comparison Functions +@cindex Float comparison functions +@cindex Comparison functions + +@deftypefun int mpf_cmp (const mpf_t @var{op1}, const mpf_t @var{op2}) +@deftypefunx int mpf_cmp_z (const mpf_t @var{op1}, const mpz_t @var{op2}) +@deftypefunx int mpf_cmp_d (const mpf_t @var{op1}, double @var{op2}) +@deftypefunx int mpf_cmp_ui (const mpf_t @var{op1}, unsigned long int @var{op2}) +@deftypefunx int mpf_cmp_si (const mpf_t @var{op1}, signed long int @var{op2}) +Compare @var{op1} and @var{op2}. Return a positive value if @math{@var{op1} > +@var{op2}}, zero if @math{@var{op1} = @var{op2}}, and a negative value if +@math{@var{op1} < @var{op2}}. + +@code{mpf_cmp_d} can be called with an infinity, but results are undefined for +a NaN. +@end deftypefun + +@deftypefun int mpf_eq (const mpf_t @var{op1}, const mpf_t @var{op2}, mp_bitcnt_t op3) +@strong{This function is mathematically ill-defined and should not be used.} + +Return non-zero if the first @var{op3} bits of @var{op1} and @var{op2} are +equal, zero otherwise. Note that numbers like e.g., 256 (binary 100000000) and +255 (binary 11111111) will never be equal by this function's measure, and +furthermore that 0 will only be equal to itself. +@end deftypefun + +@deftypefun void mpf_reldiff (mpf_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}) +Compute the relative difference between @var{op1} and @var{op2} and store the +result in @var{rop}. This is @math{@GMPabs{@var{op1}-@var{op2}}/@var{op1}}. +@end deftypefun + +@deftypefn Macro int mpf_sgn (const mpf_t @var{op}) +@cindex Sign tests +@cindex Float sign tests +Return @math{+1} if @math{@var{op} > 0}, 0 if @math{@var{op} = 0}, and +@math{-1} if @math{@var{op} < 0}. + +This function is actually implemented as a macro. It evaluates its argument +multiple times. +@end deftypefn + +@node I/O of Floats, Miscellaneous Float Functions, Float Comparison, Floating-point Functions +@comment node-name, next, previous, up +@section Input and Output Functions +@cindex Float input and output functions +@cindex Input functions +@cindex Output functions +@cindex I/O functions + +Functions that perform input from a stdio stream, and functions that output to +a stdio stream, of @code{mpf} numbers. Passing a @code{NULL} pointer for a +@var{stream} argument to any of these functions will make them read from +@code{stdin} and write to @code{stdout}, respectively. + +When using any of these functions, it is a good idea to include @file{stdio.h} +before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes +for these functions. + +See also @ref{Formatted Output} and @ref{Formatted Input}. + +@deftypefun size_t mpf_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, const mpf_t @var{op}) +Print @var{op} to @var{stream}, as a string of digits. Return the number of +bytes written, or if an error occurred, return 0. + +The mantissa is prefixed with an @samp{0.} and is in the given @var{base}, +which may vary from 2 to 62 or from @minus{}2 to @minus{}36. An exponent is +then printed, separated by an @samp{e}, or if the base is greater than 10 then +by an @samp{@@}. The exponent is always in decimal. The decimal point follows +the current locale, on systems providing @code{localeconv}. + +For @var{base} in the range 2..36, digits and lower-case letters are used; for +@minus{}2..@minus{}36, digits and upper-case letters are used; for 37..62, +digits, upper-case letters, and lower-case letters (in that significance order) +are used. + +Up to @var{n_digits} will be printed from the mantissa, except that no more +digits than are accurately representable by @var{op} will be printed. +@var{n_digits} can be 0 to select that accurate maximum. +@end deftypefun + +@deftypefun size_t mpf_inp_str (mpf_t @var{rop}, FILE *@var{stream}, int @var{base}) +Read a string in base @var{base} from @var{stream}, and put the read float in +@var{rop}. The string is of the form @samp{M@@N} or, if the base is 10 or +less, alternatively @samp{MeN}. @samp{M} is the mantissa and @samp{N} is the +exponent. The mantissa is always in the specified base. The exponent is +either in the specified base or, if @var{base} is negative, in decimal. The +decimal point expected is taken from the current locale, on systems providing +@code{localeconv}. + +The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to +@minus{}2. Negative values are used to specify that the exponent is in +decimal. + +Unlike the corresponding @code{mpz} function, the base will not be determined +from the leading characters of the string if @var{base} is 0. This is so that +numbers like @samp{0.23} are not interpreted as octal. + +Return the number of bytes read, or if an error occurred, return 0. +@end deftypefun + +@c @deftypefun void mpf_out_raw (FILE *@var{stream}, const mpf_t @var{float}) +@c Output @var{float} on stdio stream @var{stream}, in raw binary +@c format. The float is written in a portable format, with 4 bytes of +@c size information, and that many bytes of limbs. Both the size and the +@c limbs are written in decreasing significance order. +@c @end deftypefun + +@c @deftypefun void mpf_inp_raw (mpf_t @var{float}, FILE *@var{stream}) +@c Input from stdio stream @var{stream} in the format written by +@c @code{mpf_out_raw}, and put the result in @var{float}. +@c @end deftypefun + + +@node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions +@comment node-name, next, previous, up +@section Miscellaneous Functions +@cindex Miscellaneous float functions +@cindex Float miscellaneous functions + +@deftypefun void mpf_ceil (mpf_t @var{rop}, const mpf_t @var{op}) +@deftypefunx void mpf_floor (mpf_t @var{rop}, const mpf_t @var{op}) +@deftypefunx void mpf_trunc (mpf_t @var{rop}, const mpf_t @var{op}) +@cindex Rounding functions +@cindex Float rounding functions +Set @var{rop} to @var{op} rounded to an integer. @code{mpf_ceil} rounds to the +next higher integer, @code{mpf_floor} to the next lower, and @code{mpf_trunc} +to the integer towards zero. +@end deftypefun + +@deftypefun int mpf_integer_p (const mpf_t @var{op}) +Return non-zero if @var{op} is an integer. +@end deftypefun + +@deftypefun int mpf_fits_ulong_p (const mpf_t @var{op}) +@deftypefunx int mpf_fits_slong_p (const mpf_t @var{op}) +@deftypefunx int mpf_fits_uint_p (const mpf_t @var{op}) +@deftypefunx int mpf_fits_sint_p (const mpf_t @var{op}) +@deftypefunx int mpf_fits_ushort_p (const mpf_t @var{op}) +@deftypefunx int mpf_fits_sshort_p (const mpf_t @var{op}) +Return non-zero if @var{op} would fit in the respective C data type, when +truncated to an integer. +@end deftypefun + +@deftypefun void mpf_urandomb (mpf_t @var{rop}, gmp_randstate_t @var{state}, mp_bitcnt_t @var{nbits}) +@cindex Random number functions +@cindex Float random number functions +Generate a uniformly distributed random float in @var{rop}, such that @math{0 +@le{} @var{rop} < 1}, with @var{nbits} significant bits in the mantissa or +less if the precision of @var{rop} is smaller. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) before +invoking this function. +@end deftypefun + +@deftypefun void mpf_random2 (mpf_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{exp}) +Generate a random float of at most @var{max_size} limbs, with long strings of +zeros and ones in the binary representation. The exponent of the number is in +the interval @minus{}@var{exp} to @var{exp} (in limbs). This function is +useful for testing functions and algorithms, since these kind of random +numbers have proven to be more likely to trigger corner-case bugs. Negative +random numbers are generated when @var{max_size} is negative. +@end deftypefun + +@c @deftypefun size_t mpf_size (const mpf_t @var{op}) +@c Return the size of @var{op} measured in number of limbs. If @var{op} is +@c zero, the returned value will be zero. (@xref{Nomenclature}, for an +@c explanation of the concept @dfn{limb}.) +@c +@c @strong{This function is obsolete. It will disappear from future GMP +@c releases.} +@c @end deftypefun + + +@node Low-level Functions, Random Number Functions, Floating-point Functions, Top +@comment node-name, next, previous, up +@chapter Low-level Functions +@cindex Low-level functions + +This chapter describes low-level GMP functions, used to implement the +high-level GMP functions, but also intended for time-critical user code. + +These functions start with the prefix @code{mpn_}. + +@c 1. Some of these function clobber input operands. +@c + +The @code{mpn} functions are designed to be as fast as possible, @strong{not} +to provide a coherent calling interface. The different functions have somewhat +similar interfaces, but there are variations that make them hard to use. These +functions do as little as possible apart from the real multiple precision +computation, so that no time is spent on things that not all callers need. + +A source operand is specified by a pointer to the least significant limb and a +limb count. A destination operand is specified by just a pointer. It is the +responsibility of the caller to ensure that the destination has enough space +for storing the result. + +With this way of specifying operands, it is possible to perform computations on +subranges of an argument, and store the result into a subrange of a +destination. + +A common requirement for all functions is that each source area needs at least +one limb. No size argument may be zero. Unless otherwise stated, in-place +operations are allowed where source and destination are the same, but not where +they only partly overlap. + +The @code{mpn} functions are the base for the implementation of the +@code{mpz_}, @code{mpf_}, and @code{mpq_} functions. + +This example adds the number beginning at @var{s1p} and the number beginning at +@var{s2p} and writes the sum at @var{destp}. All areas have @var{n} limbs. + +@example +cy = mpn_add_n (destp, s1p, s2p, n) +@end example + +It should be noted that the @code{mpn} functions make no attempt to identify +high or low zero limbs on their operands, or other special forms. On random +data such cases will be unlikely and it'd be wasteful for every function to +check every time. An application knowing something about its data can take +steps to trim or perhaps split its calculations. +@c +@c For reference, within gmp mpz_t operands never have high zero limbs, and +@c we rate low zero limbs as unlikely too (or something an application should +@c handle). This is a prime motivation for not stripping zero limbs in say +@c mpn_mul_n etc. +@c +@c Other applications doing variable-length calculations will quite likely do +@c something similar to mpz. And even if not then it's highly likely zero +@c limb stripping can be done at just a few judicious points, which will be +@c more efficient than having lots of mpn functions checking every time. + +@sp 1 +@noindent +In the notation used below, a source operand is identified by the pointer to +the least significant limb, and the limb count in braces. For example, +@{@var{s1p}, @var{s1n}@}. + +@deftypefun mp_limb_t mpn_add_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Add @{@var{s1p}, @var{n}@} and @{@var{s2p}, @var{n}@}, and write the @var{n} +least significant limbs of the result to @var{rp}. Return carry, either 0 or +1. + +This is the lowest-level function for addition. It is the preferred function +for addition, since it is written in assembly for most CPUs. For addition of +a variable to itself (i.e., @var{s1p} equals @var{s2p}) use @code{mpn_lshift} +with a count of 1 for optimal speed. +@end deftypefun + +@deftypefun mp_limb_t mpn_add_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}, mp_limb_t @var{s2limb}) +Add @{@var{s1p}, @var{n}@} and @var{s2limb}, and write the @var{n} least +significant limbs of the result to @var{rp}. Return carry, either 0 or 1. +@end deftypefun + +@deftypefun mp_limb_t mpn_add (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1n}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2n}) +Add @{@var{s1p}, @var{s1n}@} and @{@var{s2p}, @var{s2n}@}, and write the +@var{s1n} least significant limbs of the result to @var{rp}. Return carry, +either 0 or 1. + +This function requires that @var{s1n} is greater than or equal to @var{s2n}. +@end deftypefun + +@deftypefun mp_limb_t mpn_sub_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Subtract @{@var{s2p}, @var{n}@} from @{@var{s1p}, @var{n}@}, and write the +@var{n} least significant limbs of the result to @var{rp}. Return borrow, +either 0 or 1. + +This is the lowest-level function for subtraction. It is the preferred +function for subtraction, since it is written in assembly for most CPUs. +@end deftypefun + +@deftypefun mp_limb_t mpn_sub_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}, mp_limb_t @var{s2limb}) +Subtract @var{s2limb} from @{@var{s1p}, @var{n}@}, and write the @var{n} least +significant limbs of the result to @var{rp}. Return borrow, either 0 or 1. +@end deftypefun + +@deftypefun mp_limb_t mpn_sub (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1n}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2n}) +Subtract @{@var{s2p}, @var{s2n}@} from @{@var{s1p}, @var{s1n}@}, and write the +@var{s1n} least significant limbs of the result to @var{rp}. Return borrow, +either 0 or 1. + +This function requires that @var{s1n} is greater than or equal to +@var{s2n}. +@end deftypefun + +@deftypefun mp_limb_t mpn_neg (mp_limb_t *@var{rp}, const mp_limb_t *@var{sp}, mp_size_t @var{n}) +Perform the negation of @{@var{sp}, @var{n}@}, and write the result to +@{@var{rp}, @var{n}@}. This is equivalent to calling @code{mpn_sub_n} with an +@var{n}-limb zero minuend and passing @{@var{sp}, @var{n}@} as subtrahend. +Return borrow, either 0 or 1. +@end deftypefun + +@deftypefun void mpn_mul_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Multiply @{@var{s1p}, @var{n}@} and @{@var{s2p}, @var{n}@}, and write the +2*@var{n}-limb result to @var{rp}. + +The destination has to have space for 2*@var{n} limbs, even if the product's +most significant limb is zero. No overlap is permitted between the +destination and either source. + +If the two input operands are the same, use @code{mpn_sqr}. +@end deftypefun + +@deftypefun mp_limb_t mpn_mul (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1n}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2n}) +Multiply @{@var{s1p}, @var{s1n}@} and @{@var{s2p}, @var{s2n}@}, and write the +(@var{s1n}+@var{s2n})-limb result to @var{rp}. Return the most significant +limb of the result. + +The destination has to have space for @var{s1n} + @var{s2n} limbs, even if the +product's most significant limb is zero. No overlap is permitted between the +destination and either source. + +This function requires that @var{s1n} is greater than or equal to @var{s2n}. +@end deftypefun + +@deftypefun void mpn_sqr (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}) +Compute the square of @{@var{s1p}, @var{n}@} and write the 2*@var{n}-limb +result to @var{rp}. + +The destination has to have space for 2@var{n} limbs, even if the result's +most significant limb is zero. No overlap is permitted between the +destination and the source. +@end deftypefun + +@deftypefun mp_limb_t mpn_mul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{n}@} by @var{s2limb}, and write the @var{n} least +significant limbs of the product to @var{rp}. Return the most significant +limb of the product. @{@var{s1p}, @var{n}@} and @{@var{rp}, @var{n}@} are +allowed to overlap provided @math{@var{rp} @le{} @var{s1p}}. + +This is a low-level function that is a building block for general +multiplication as well as other operations in GMP@. It is written in assembly +for most CPUs. + +Don't call this function if @var{s2limb} is a power of 2; use @code{mpn_lshift} +with a count equal to the logarithm of @var{s2limb} instead, for optimal speed. +@end deftypefun + +@deftypefun mp_limb_t mpn_addmul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{n}@} and @var{s2limb}, and add the @var{n} least +significant limbs of the product to @{@var{rp}, @var{n}@} and write the result +to @var{rp}. Return the most significant limb of the product, plus carry-out +from the addition. @{@var{s1p}, @var{n}@} and @{@var{rp}, @var{n}@} are +allowed to overlap provided @math{@var{rp} @le{} @var{s1p}}. + +This is a low-level function that is a building block for general +multiplication as well as other operations in GMP@. It is written in assembly +for most CPUs. +@end deftypefun + +@deftypefun mp_limb_t mpn_submul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{n}@} and @var{s2limb}, and subtract the @var{n} +least significant limbs of the product from @{@var{rp}, @var{n}@} and write the +result to @var{rp}. Return the most significant limb of the product, plus +borrow-out from the subtraction. @{@var{s1p}, @var{n}@} and @{@var{rp}, +@var{n}@} are allowed to overlap provided @math{@var{rp} @le{} @var{s1p}}. + +This is a low-level function that is a building block for general +multiplication and division as well as other operations in GMP@. It is written +in assembly for most CPUs. +@end deftypefun + +@deftypefun void mpn_tdiv_qr (mp_limb_t *@var{qp}, mp_limb_t *@var{rp}, mp_size_t @var{qxn}, const mp_limb_t *@var{np}, mp_size_t @var{nn}, const mp_limb_t *@var{dp}, mp_size_t @var{dn}) +Divide @{@var{np}, @var{nn}@} by @{@var{dp}, @var{dn}@} and put the quotient +at @{@var{qp}, @var{nn}@minus{}@var{dn}+1@} and the remainder at @{@var{rp}, +@var{dn}@}. The quotient is rounded towards 0. + +No overlap is permitted between arguments, except that @var{np} might equal +@var{rp}. The dividend size @var{nn} must be greater than or equal to divisor +size @var{dn}. The most significant limb of the divisor must be non-zero. The +@var{qxn} operand must be zero. +@end deftypefun + +@deftypefun mp_limb_t mpn_divrem (mp_limb_t *@var{r1p}, mp_size_t @var{qxn}, mp_limb_t *@var{rs2p}, mp_size_t @var{rs2n}, const mp_limb_t *@var{s3p}, mp_size_t @var{s3n}) +[This function is obsolete. Please call @code{mpn_tdiv_qr} instead for best +performance.] + +Divide @{@var{rs2p}, @var{rs2n}@} by @{@var{s3p}, @var{s3n}@}, and write the +quotient at @var{r1p}, with the exception of the most significant limb, which +is returned. The remainder replaces the dividend at @var{rs2p}; it will be +@var{s3n} limbs long (i.e., as many limbs as the divisor). + +In addition to an integer quotient, @var{qxn} fraction limbs are developed, and +stored after the integral limbs. For most usages, @var{qxn} will be zero. + +It is required that @var{rs2n} is greater than or equal to @var{s3n}. It is +required that the most significant bit of the divisor is set. + +If the quotient is not needed, pass @var{rs2p} + @var{s3n} as @var{r1p}. Aside +from that special case, no overlap between arguments is permitted. + +Return the most significant limb of the quotient, either 0 or 1. + +The area at @var{r1p} needs to be @var{rs2n} @minus{} @var{s3n} + @var{qxn} +limbs large. +@end deftypefun + +@deftypefn Function mp_limb_t mpn_divrem_1 (mp_limb_t *@var{r1p}, mp_size_t @var{qxn}, @w{mp_limb_t *@var{s2p}}, mp_size_t @var{s2n}, mp_limb_t @var{s3limb}) +@deftypefnx Macro mp_limb_t mpn_divmod_1 (mp_limb_t *@var{r1p}, mp_limb_t *@var{s2p}, @w{mp_size_t @var{s2n}}, @w{mp_limb_t @var{s3limb}}) +Divide @{@var{s2p}, @var{s2n}@} by @var{s3limb}, and write the quotient at +@var{r1p}. Return the remainder. + +The integer quotient is written to @{@var{r1p}+@var{qxn}, @var{s2n}@} and in +addition @var{qxn} fraction limbs are developed and written to @{@var{r1p}, +@var{qxn}@}. Either or both @var{s2n} and @var{qxn} can be zero. For most +usages, @var{qxn} will be zero. + +@code{mpn_divmod_1} exists for upward source compatibility and is simply a +macro calling @code{mpn_divrem_1} with a @var{qxn} of 0. + +The areas at @var{r1p} and @var{s2p} have to be identical or completely +separate, not partially overlapping. +@end deftypefn + +@deftypefun mp_limb_t mpn_divmod (mp_limb_t *@var{r1p}, mp_limb_t *@var{rs2p}, mp_size_t @var{rs2n}, const mp_limb_t *@var{s3p}, mp_size_t @var{s3n}) +[This function is obsolete. Please call @code{mpn_tdiv_qr} instead for best +performance.] +@end deftypefun + +@deftypefun void mpn_divexact_1 (mp_limb_t * @var{rp}, const mp_limb_t * @var{sp}, mp_size_t @var{n}, mp_limb_t @var{d}) +Divide @{@var{sp}, @var{n}@} by @var{d}, expecting it to divide exactly, and +writing the result to @{@var{rp}, @var{n}@}. If @var{d} doesn't divide +exactly, the value written to @{@var{rp}, @var{n}@} is undefined. The areas at +@var{rp} and @var{sp} have to be identical or completely separate, not +partially overlapping. +@end deftypefun + +@deftypefn Macro mp_limb_t mpn_divexact_by3 (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{n}}) +@deftypefnx Function mp_limb_t mpn_divexact_by3c (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{n}}, mp_limb_t @var{carry}) +Divide @{@var{sp}, @var{n}@} by 3, expecting it to divide exactly, and writing +the result to @{@var{rp}, @var{n}@}. If 3 divides exactly, the return value is +zero and the result is the quotient. If not, the return value is non-zero and +the result won't be anything useful. + +@code{mpn_divexact_by3c} takes an initial carry parameter, which can be the +return value from a previous call, so a large calculation can be done piece by +piece from low to high. @code{mpn_divexact_by3} is simply a macro calling +@code{mpn_divexact_by3c} with a 0 carry parameter. + +These routines use a multiply-by-inverse and will be faster than +@code{mpn_divrem_1} on CPUs with fast multiplication but slow division. + +The source @math{a}, result @math{q}, size @math{n}, initial carry @math{i}, +and return value @math{c} satisfy @m{cb^n+a-i=3q, c*b^n + a-i = 3*q}, where +@m{b=2\GMPraise{@code{GMP\_NUMB\_BITS}}, b=2^GMP_NUMB_BITS}. The +return @math{c} is always 0, 1 or 2, and the initial carry @math{i} must also +be 0, 1 or 2 (these are both borrows really). When @math{c=0} clearly +@math{q=(a-i)/3}. When @m{c \neq 0, c!=0}, the remainder @math{(a-i) @bmod{} +3} is given by @math{3-c}, because @math{b @equiv{} 1 @bmod{} 3} (when +@code{mp_bits_per_limb} is even, which is always so currently). +@end deftypefn + +@deftypefun mp_limb_t mpn_mod_1 (const mp_limb_t *@var{s1p}, mp_size_t @var{s1n}, mp_limb_t @var{s2limb}) +Divide @{@var{s1p}, @var{s1n}@} by @var{s2limb}, and return the remainder. +@var{s1n} can be zero. +@end deftypefun + +@deftypefun mp_limb_t mpn_lshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{sp}, mp_size_t @var{n}, unsigned int @var{count}) +Shift @{@var{sp}, @var{n}@} left by @var{count} bits, and write the result to +@{@var{rp}, @var{n}@}. The bits shifted out at the left are returned in the +least significant @var{count} bits of the return value (the rest of the return +value is zero). + +@var{count} must be in the range 1 to @nicode{mp_bits_per_limb}@math{{}-1}. The +regions @{@var{sp}, @var{n}@} and @{@var{rp}, @var{n}@} may overlap, provided +@math{@var{rp} @ge{} @var{sp}}. + +This function is written in assembly for most CPUs. +@end deftypefun + +@deftypefun mp_limb_t mpn_rshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{sp}, mp_size_t @var{n}, unsigned int @var{count}) +Shift @{@var{sp}, @var{n}@} right by @var{count} bits, and write the result to +@{@var{rp}, @var{n}@}. The bits shifted out at the right are returned in the +most significant @var{count} bits of the return value (the rest of the return +value is zero). + +@var{count} must be in the range 1 to @nicode{mp_bits_per_limb}@math{{}-1}. The +regions @{@var{sp}, @var{n}@} and @{@var{rp}, @var{n}@} may overlap, provided +@math{@var{rp} @le{} @var{sp}}. + +This function is written in assembly for most CPUs. +@end deftypefun + +@deftypefun int mpn_cmp (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Compare @{@var{s1p}, @var{n}@} and @{@var{s2p}, @var{n}@} and return a +positive value if @math{@var{s1} > @var{s2}}, 0 if they are equal, or a +negative value if @math{@var{s1} < @var{s2}}. +@end deftypefun + +@deftypefun int mpn_zero_p (const mp_limb_t *@var{sp}, mp_size_t @var{n}) +Test @{@var{sp}, @var{n}@} and return 1 if the operand is zero, 0 otherwise. +@end deftypefun + +@deftypefun mp_size_t mpn_gcd (mp_limb_t *@var{rp}, mp_limb_t *@var{xp}, mp_size_t @var{xn}, mp_limb_t *@var{yp}, mp_size_t @var{yn}) +Set @{@var{rp}, @var{retval}@} to the greatest common divisor of @{@var{xp}, +@var{xn}@} and @{@var{yp}, @var{yn}@}. The result can be up to @var{yn} limbs, +the return value is the actual number produced. Both source operands are +destroyed. + +It is required that @math{@var{xn} @ge @var{yn} > 0}, the most significant +limb of @{@var{yp}, @var{yn}@} must be non-zero, and at least one of +the two operands must be odd. No overlap is permitted +between @{@var{xp}, @var{xn}@} and @{@var{yp}, @var{yn}@}. +@end deftypefun + +@deftypefun mp_limb_t mpn_gcd_1 (const mp_limb_t *@var{xp}, mp_size_t @var{xn}, mp_limb_t @var{ylimb}) +Return the greatest common divisor of @{@var{xp}, @var{xn}@} and @var{ylimb}. +Both operands must be non-zero. +@end deftypefun + +@deftypefun mp_size_t mpn_gcdext (mp_limb_t *@var{gp}, mp_limb_t *@var{sp}, mp_size_t *@var{sn}, mp_limb_t *@var{up}, mp_size_t @var{un}, mp_limb_t *@var{vp}, mp_size_t @var{vn}) +Let @m{U,@var{U}} be defined by @{@var{up}, @var{un}@} and let @m{V,@var{V}} be +defined by @{@var{vp}, @var{vn}@}. + +Compute the greatest common divisor @math{G} of @math{U} and @math{V}. Compute +a cofactor @math{S} such that @math{G = US + VT}. The second cofactor @var{T} +is not computed but can easily be obtained from @m{(G - US) / V, (@var{G} - +@var{U}*@var{S}) / @var{V}} (the division will be exact). It is required that +@math{@var{un} @ge @var{vn} > 0}, and the most significant +limb of @{@var{vp}, @var{vn}@} must be non-zero. + +@math{S} satisfies @math{S = 1} or @math{@GMPabs{S} < V / (2 G)}. @math{S = +0} if and only if @math{V} divides @math{U} (i.e., @math{G = V}). + +Store @math{G} at @var{gp} and let the return value define its limb count. +Store @math{S} at @var{sp} and let |*@var{sn}| define its limb count. @math{S} +can be negative; when this happens *@var{sn} will be negative. The area at +@var{gp} should have room for @var{vn} limbs and the area at @var{sp} should +have room for @math{@var{vn}+1} limbs. + +Both source operands are destroyed. + +Compatibility notes: GMP 4.3.0 and 4.3.1 defined @math{S} less strictly. +Earlier as well as later GMP releases define @math{S} as described here. +GMP releases before GMP 4.3.0 required additional space for both input and output +areas. More precisely, the areas @{@var{up}, @math{@var{un}+1}@} and +@{@var{vp}, @math{@var{vn}+1}@} were destroyed (i.e.@: the operands plus an +extra limb past the end of each), and the areas pointed to by @var{gp} and +@var{sp} should each have room for @math{@var{un}+1} limbs. +@end deftypefun + +@deftypefun mp_size_t mpn_sqrtrem (mp_limb_t *@var{r1p}, mp_limb_t *@var{r2p}, const mp_limb_t *@var{sp}, mp_size_t @var{n}) +Compute the square root of @{@var{sp}, @var{n}@} and put the result at +@{@var{r1p}, @math{@GMPceil{@var{n}/2}}@} and the remainder at @{@var{r2p}, +@var{retval}@}. @var{r2p} needs space for @var{n} limbs, but the return value +indicates how many are produced. + +The most significant limb of @{@var{sp}, @var{n}@} must be non-zero. The +areas @{@var{r1p}, @math{@GMPceil{@var{n}/2}}@} and @{@var{sp}, @var{n}@} must +be completely separate. The areas @{@var{r2p}, @var{n}@} and @{@var{sp}, +@var{n}@} must be either identical or completely separate. + +If the remainder is not wanted then @var{r2p} can be @code{NULL}, and in this +case the return value is zero or non-zero according to whether the remainder +would have been zero or non-zero. + +A return value of zero indicates a perfect square. See also +@code{mpn_perfect_square_p}. +@end deftypefun + +@deftypefun size_t mpn_sizeinbase (const mp_limb_t *@var{xp}, mp_size_t @var{n}, int @var{base}) +Return the size of @{@var{xp},@var{n}@} measured in number of digits in the +given @var{base}. @var{base} can vary from 2 to 62. Requires @math{@var{n} > 0} +and @math{@var{xp}[@var{n}-1] > 0}. The result will be either exact or +1 too big. If @var{base} is a power of 2, the result is always exact. +@end deftypefun + +@deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t *@var{s1p}, mp_size_t @var{s1n}) +Convert @{@var{s1p}, @var{s1n}@} to a raw unsigned char array at @var{str} in +base @var{base}, and return the number of characters produced. There may be +leading zeros in the string. The string is not in ASCII; to convert it to +printable format, add the ASCII codes for @samp{0} or @samp{A}, depending on +the base and range. @var{base} can vary from 2 to 256. + +The most significant limb of the input @{@var{s1p}, @var{s1n}@} must be +non-zero. The input @{@var{s1p}, @var{s1n}@} is clobbered, except when +@var{base} is a power of 2, in which case it's unchanged. + +The area at @var{str} has to have space for the largest possible number +represented by a @var{s1n} long limb array, plus one extra character. +@end deftypefun + +@deftypefun mp_size_t mpn_set_str (mp_limb_t *@var{rp}, const unsigned char *@var{str}, size_t @var{strsize}, int @var{base}) +Convert bytes @{@var{str},@var{strsize}@} in the given @var{base} to limbs at +@var{rp}. + +@math{@var{str}[0]} is the most significant input byte and +@math{@var{str}[@var{strsize}-1]} is the least significant input byte. Each +byte should be a value in the range 0 to @math{@var{base}-1}, not an ASCII +character. @var{base} can vary from 2 to 256. + +The converted value is @{@var{rp},@var{rn}@} where @var{rn} is the return +value. If the most significant input byte @math{@var{str}[0]} is non-zero, +then @math{@var{rp}[@var{rn}-1]} will be non-zero, else +@math{@var{rp}[@var{rn}-1]} and some number of subsequent limbs may be zero. + +The area at @var{rp} has to have space for the largest possible number with +@var{strsize} digits in the chosen base, plus one extra limb. + +The input must have at least one byte, and no overlap is permitted between +@{@var{str},@var{strsize}@} and the result at @var{rp}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpn_scan0 (const mp_limb_t *@var{s1p}, mp_bitcnt_t @var{bit}) +Scan @var{s1p} from bit position @var{bit} for the next clear bit. + +It is required that there be a clear bit within the area at @var{s1p} at or +beyond bit position @var{bit}, so that the function has something to return. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpn_scan1 (const mp_limb_t *@var{s1p}, mp_bitcnt_t @var{bit}) +Scan @var{s1p} from bit position @var{bit} for the next set bit. + +It is required that there be a set bit within the area at @var{s1p} at or +beyond bit position @var{bit}, so that the function has something to return. +@end deftypefun + +@deftypefun void mpn_random (mp_limb_t *@var{r1p}, mp_size_t @var{r1n}) +@deftypefunx void mpn_random2 (mp_limb_t *@var{r1p}, mp_size_t @var{r1n}) +Generate a random number of length @var{r1n} and store it at @var{r1p}. The +most significant limb is always non-zero. @code{mpn_random} generates +uniformly distributed limb data, @code{mpn_random2} generates long strings of +zeros and ones in the binary representation. + +@code{mpn_random2} is intended for testing the correctness of the @code{mpn} +routines. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpn_popcount (const mp_limb_t *@var{s1p}, mp_size_t @var{n}) +Count the number of set bits in @{@var{s1p}, @var{n}@}. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpn_hamdist (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Compute the hamming distance between @{@var{s1p}, @var{n}@} and @{@var{s2p}, +@var{n}@}, which is the number of bit positions where the two operands have +different bit values. +@end deftypefun + +@deftypefun int mpn_perfect_square_p (const mp_limb_t *@var{s1p}, mp_size_t @var{n}) +Return non-zero iff @{@var{s1p}, @var{n}@} is a perfect square. +The most significant limb of the input @{@var{s1p}, @var{n}@} must be +non-zero. +@end deftypefun + +@deftypefun void mpn_and_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical and of @{@var{s1p}, @var{n}@} and @{@var{s2p}, +@var{n}@}, and write the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_ior_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical inclusive or of @{@var{s1p}, @var{n}@} and +@{@var{s2p}, @var{n}@}, and write the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_xor_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical exclusive or of @{@var{s1p}, @var{n}@} and +@{@var{s2p}, @var{n}@}, and write the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_andn_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical and of @{@var{s1p}, @var{n}@} and the bitwise +complement of @{@var{s2p}, @var{n}@}, and write the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_iorn_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical inclusive or of @{@var{s1p}, @var{n}@} and the bitwise +complement of @{@var{s2p}, @var{n}@}, and write the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_nand_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical and of @{@var{s1p}, @var{n}@} and @{@var{s2p}, +@var{n}@}, and write the bitwise complement of the result to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_nior_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical inclusive or of @{@var{s1p}, @var{n}@} and +@{@var{s2p}, @var{n}@}, and write the bitwise complement of the result to +@{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_xnor_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +Perform the bitwise logical exclusive or of @{@var{s1p}, @var{n}@} and +@{@var{s2p}, @var{n}@}, and write the bitwise complement of the result to +@{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_com (mp_limb_t *@var{rp}, const mp_limb_t *@var{sp}, mp_size_t @var{n}) +Perform the bitwise complement of @{@var{sp}, @var{n}@}, and write the result +to @{@var{rp}, @var{n}@}. +@end deftypefun + +@deftypefun void mpn_copyi (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}) +Copy from @{@var{s1p}, @var{n}@} to @{@var{rp}, @var{n}@}, increasingly. +@end deftypefun + +@deftypefun void mpn_copyd (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{n}) +Copy from @{@var{s1p}, @var{n}@} to @{@var{rp}, @var{n}@}, decreasingly. +@end deftypefun + +@deftypefun void mpn_zero (mp_limb_t *@var{rp}, mp_size_t @var{n}) +Zero @{@var{rp}, @var{n}@}. +@end deftypefun + +@sp 1 +@section Low-level functions for cryptography +@cindex Low-level functions for cryptography +@cindex Cryptography functions, low-level + +The functions prefixed with @code{mpn_sec_} and @code{mpn_cnd_} are designed to +perform the exact same low-level operations and have the same cache access +patterns for any two same-size arguments, assuming that function arguments are +placed at the same position and that the machine state is identical upon +function entry. These functions are intended for cryptographic purposes, where +resilience to side-channel attacks is desired. + +These functions are less efficient than their ``leaky'' counterparts; their +performance for operands of the sizes typically used for cryptographic +applications is between 15% and 100% worse. For larger operands, these +functions might be inadequate, since they rely on asymptotically elementary +algorithms. + +These functions do not make any explicit allocations. Those of these functions +that need scratch space accept a scratch space operand. This convention allows +callers to keep sensitive data in designated memory areas. Note however that +compilers may choose to spill scalar values used within these functions to +their stack frame and that such scalars may contain sensitive data. + +In addition to these specially crafted functions, the following @code{mpn} +functions are naturally side-channel resistant: @code{mpn_add_n}, +@code{mpn_sub_n}, @code{mpn_lshift}, @code{mpn_rshift}, @code{mpn_zero}, +@code{mpn_copyi}, @code{mpn_copyd}, @code{mpn_com}, and the logical function +(@code{mpn_and_n}, etc). + +There are some exceptions from the side-channel resilience: (1) Some assembly +implementations of @code{mpn_lshift} identify shift-by-one as a special case. +This is a problem iff the shift count is a function of sensitive data. (2) +Alpha ev6 and Pentium4 using 64-bit limbs have leaky @code{mpn_add_n} and +@code{mpn_sub_n}. (3) Alpha ev6 has a leaky @code{mpn_mul_1} which also makes +@code{mpn_sec_mul} on those systems unsafe. + +@deftypefun mp_limb_t mpn_cnd_add_n (mp_limb_t @var{cnd}, mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +@deftypefunx mp_limb_t mpn_cnd_sub_n (mp_limb_t @var{cnd}, mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{n}) +These functions do conditional addition and subtraction. If @var{cnd} is +non-zero, they produce the same result as a regular @code{mpn_add_n} or +@code{mpn_sub_n}, and if @var{cnd} is zero, they copy @{@var{s1p},@var{n}@} to +the result area and return zero. The functions are designed to have timing and +memory access patterns depending only on size and location of the data areas, +but independent of the condition @var{cnd}. Like for @code{mpn_add_n} and +@code{mpn_sub_n}, on most machines, the timing will also be independent of the +actual limb values. +@end deftypefun + +@deftypefun mp_limb_t mpn_sec_add_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{ap}, mp_size_t @var{n}, mp_limb_t @var{b}, mp_limb_t *@var{tp}) +@deftypefunx mp_limb_t mpn_sec_sub_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{ap}, mp_size_t @var{n}, mp_limb_t @var{b}, mp_limb_t *@var{tp}) +Set @var{R} to @var{A} + @var{b} or @var{A} - @var{b}, respectively, where +@var{R} = @{@var{rp},@var{n}@}, @var{A} = @{@var{ap},@var{n}@}, and @var{b} is +a single limb. Returns carry. + +These functions take @math{O(N)} time, unlike the leaky functions +@code{mpn_add_1} which are @math{O(1)} on average. They require scratch space +of @code{mpn_sec_add_1_itch(@var{n})} and @code{mpn_sec_sub_1_itch(@var{n})} +limbs, respectively, to be passed in the @var{tp} parameter. The scratch space +requirements are guaranteed to be at most @var{n} limbs, and increase +monotonously in the operand size. +@end deftypefun + +@deftypefun void mpn_cnd_swap (mp_limb_t @var{cnd}, volatile mp_limb_t *@var{ap}, volatile mp_limb_t *@var{bp}, mp_size_t @var{n}) +If @var{cnd} is non-zero, swaps the contents of the areas @{@var{ap},@var{n}@} +and @{@var{bp},@var{n}@}. Otherwise, the areas are left unmodified. +Implemented using logical operations on the limbs, with the same memory +accesses independent of the value of @var{cnd}. +@end deftypefun + +@deftypefun void mpn_sec_mul (mp_limb_t *@var{rp}, const mp_limb_t *@var{ap}, mp_size_t @var{an}, const mp_limb_t *@var{bp}, mp_size_t @var{bn}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_mul_itch (mp_size_t @var{an}, mp_size_t @var{bn}) +Set @var{R} to @math{A @times{} B}, where @var{A} = @{@var{ap},@var{an}@}, +@var{B} = @{@var{bp},@var{bn}@}, and @var{R} = +@{@var{rp},@math{@var{an}+@var{bn}}@}. + +It is required that @math{@var{an} @ge @var{bn} > 0}. + +No overlapping between @var{R} and the input operands is allowed. For +@math{@var{A} = @var{B}}, use @code{mpn_sec_sqr} for optimal performance. + +This function requires scratch space of @code{mpn_sec_mul_itch(@var{an}, +@var{bn})} limbs to be passed in the @var{tp} parameter. The scratch space +requirements are guaranteed to increase monotonously in the operand sizes. +@end deftypefun + + +@deftypefun void mpn_sec_sqr (mp_limb_t *@var{rp}, const mp_limb_t *@var{ap}, mp_size_t @var{an}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_sqr_itch (mp_size_t @var{an}) +Set @var{R} to @math{A^2}, where @var{A} = @{@var{ap},@var{an}@}, and @var{R} = +@{@var{rp},@math{2@var{an}}@}. + +It is required that @math{@var{an} > 0}. + +No overlapping between @var{R} and the input operands is allowed. + +This function requires scratch space of @code{mpn_sec_sqr_itch(@var{an})} limbs +to be passed in the @var{tp} parameter. The scratch space requirements are +guaranteed to increase monotonously in the operand size. +@end deftypefun + + +@deftypefun void mpn_sec_powm (mp_limb_t *@var{rp}, const mp_limb_t *@var{bp}, mp_size_t @var{bn}, const mp_limb_t *@var{ep}, mp_bitcnt_t @var{enb}, const mp_limb_t *@var{mp}, mp_size_t @var{n}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_powm_itch (mp_size_t @var{bn}, mp_bitcnt_t @var{enb}, size_t @var{n}) +Set @var{R} to @m{B^E \bmod @var{M}, (@var{B} raised to @var{E}) modulo +@var{M}}, where @var{R} = @{@var{rp},@var{n}@}, @var{M} = @{@var{mp},@var{n}@}, +and @var{E} = @{@var{ep},@math{@GMPceil{@var{enb} / +@code{GMP\_NUMB\_BITS}}}@}. + +It is required that @math{@var{B} > 0}, that @math{@var{M} > 0} is odd, and +that @m{@var{E} < 2@GMPraise{@var{enb}}, @var{E} < 2^@var{enb}}, with @math{@var{enb} > 0}. + +No overlapping between @var{R} and the input operands is allowed. + +This function requires scratch space of @code{mpn_sec_powm_itch(@var{bn}, +@var{enb}, @var{n})} limbs to be passed in the @var{tp} parameter. The scratch +space requirements are guaranteed to increase monotonously in the operand +sizes. +@end deftypefun + +@deftypefun void mpn_sec_tabselect (mp_limb_t *@var{rp}, const mp_limb_t *@var{tab}, mp_size_t @var{n}, mp_size_t @var{nents}, mp_size_t @var{which}) +Select entry @var{which} from table @var{tab}, which has @var{nents} entries, each @var{n} +limbs. Store the selected entry at @var{rp}. + +This function reads the entire table to avoid side-channel information leaks. +@end deftypefun + +@deftypefun mp_limb_t mpn_sec_div_qr (mp_limb_t *@var{qp}, mp_limb_t *@var{np}, mp_size_t @var{nn}, const mp_limb_t *@var{dp}, mp_size_t @var{dn}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_div_qr_itch (mp_size_t @var{nn}, mp_size_t @var{dn}) + +Set @var{Q} to @m{\lfloor @var{N} / @var{D}\rfloor, the truncated quotient +@var{N} / @var{D}} and @var{R} to @m{@var{N} \bmod @var{D}, @var{N} modulo +@var{D}}, where @var{N} = @{@var{np},@var{nn}@}, @var{D} = +@{@var{dp},@var{dn}@}, @var{Q}'s most significant limb is the function return +value and the remaining limbs are @{@var{qp},@var{nn-dn}@}, and @var{R} = +@{@var{np},@var{dn}@}. + +It is required that @math{@var{nn} @ge @var{dn} @ge 1}, and that +@m{@var{dp}[@var{dn}-1] @neq 0, @var{dp}[@var{dn}-1] != 0}. This does not +imply that @math{@var{N} @ge @var{D}} since @var{N} might be zero-padded. + +Note the overlapping between @var{N} and @var{R}. No other operand overlapping +is allowed. The entire space occupied by @var{N} is overwritten. + +This function requires scratch space of @code{mpn_sec_div_qr_itch(@var{nn}, +@var{dn})} limbs to be passed in the @var{tp} parameter. +@end deftypefun + +@deftypefun void mpn_sec_div_r (mp_limb_t *@var{np}, mp_size_t @var{nn}, const mp_limb_t *@var{dp}, mp_size_t @var{dn}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_div_r_itch (mp_size_t @var{nn}, mp_size_t @var{dn}) + +Set @var{R} to @m{@var{N} \bmod @var{D}, @var{N} modulo @var{D}}, where @var{N} += @{@var{np},@var{nn}@}, @var{D} = @{@var{dp},@var{dn}@}, and @var{R} = +@{@var{np},@var{dn}@}. + +It is required that @math{@var{nn} @ge @var{dn} @ge 1}, and that +@m{@var{dp}[@var{dn}-1] @neq 0, @var{dp}[@var{dn}-1] != 0}. This does not +imply that @math{@var{N} @ge @var{D}} since @var{N} might be zero-padded. + +Note the overlapping between @var{N} and @var{R}. No other operand overlapping +is allowed. The entire space occupied by @var{N} is overwritten. + +This function requires scratch space of @code{mpn_sec_div_r_itch(@var{nn}, +@var{dn})} limbs to be passed in the @var{tp} parameter. +@end deftypefun + +@deftypefun int mpn_sec_invert (mp_limb_t *@var{rp}, mp_limb_t *@var{ap}, const mp_limb_t *@var{mp}, mp_size_t @var{n}, mp_bitcnt_t @var{nbcnt}, mp_limb_t *@var{tp}) +@deftypefunx mp_size_t mpn_sec_invert_itch (mp_size_t @var{n}) +Set @var{R} to @m{@var{A}^{-1} \bmod @var{M}, the inverse of @var{A} modulo +@var{M}}, where @var{R} = @{@var{rp},@var{n}@}, @var{A} = @{@var{ap},@var{n}@}, +and @var{M} = @{@var{mp},@var{n}@}. @strong{This function's interface is +preliminary.} + +If an inverse exists, return 1, otherwise return 0 and leave @var{R} +undefined. In either case, the input @var{A} is destroyed. + +It is required that @var{M} is odd, and that @math{@var{nbcnt} @ge +@GMPceil{\log(@var{A}+1)} + @GMPceil{\log(@var{M}+1)}}. A safe choice is +@m{@var{nbcnt} = 2@var{n} @times{} @code{GMP\_NUMB\_BITS}, @var{nbcnt} = 2 +@times{} @var{n} @times{} GMP_NUMB_BITS}, but a smaller value might improve +performance if @var{M} or @var{A} are known to have leading zero bits. + +This function requires scratch space of @code{mpn_sec_invert_itch(@var{n})} +limbs to be passed in the @var{tp} parameter. +@end deftypefun + + +@sp 1 +@section Nails +@cindex Nails + +@strong{Everything in this section is highly experimental and may disappear or +be subject to incompatible changes in a future version of GMP.} + +Nails are an experimental feature whereby a few bits are left unused at the +top of each @code{mp_limb_t}. This can significantly improve carry handling +on some processors. + +All the @code{mpn} functions accepting limb data will expect the nail bits to +be zero on entry, and will return data with the nails similarly all zero. +This applies both to limb vectors and to single limb arguments. + +Nails can be enabled by configuring with @samp{--enable-nails}. By default +the number of bits will be chosen according to what suits the host processor, +but a particular number can be selected with @samp{--enable-nails=N}. + +At the mpn level, a nail build is neither source nor binary compatible with a +non-nail build, strictly speaking. But programs acting on limbs only through +the mpn functions are likely to work equally well with either build, and +judicious use of the definitions below should make any program compatible with +either build, at the source level. + +For the higher level routines, meaning @code{mpz} etc, a nail build should be +fully source and binary compatible with a non-nail build. + +@defmac GMP_NAIL_BITS +@defmacx GMP_NUMB_BITS +@defmacx GMP_LIMB_BITS +@code{GMP_NAIL_BITS} is the number of nail bits, or 0 when nails are not in +use. @code{GMP_NUMB_BITS} is the number of data bits in a limb. +@code{GMP_LIMB_BITS} is the total number of bits in an @code{mp_limb_t}. In +all cases + +@example +GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS +@end example +@end defmac + +@defmac GMP_NAIL_MASK +@defmacx GMP_NUMB_MASK +Bit masks for the nail and number parts of a limb. @code{GMP_NAIL_MASK} is 0 +when nails are not in use. + +@code{GMP_NAIL_MASK} is not often needed, since the nail part can be obtained +with @code{x >> GMP_NUMB_BITS}, and that means one less large constant, which +can help various RISC chips. +@end defmac + +@defmac GMP_NUMB_MAX +The maximum value that can be stored in the number part of a limb. This is +the same as @code{GMP_NUMB_MASK}, but can be used for clarity when doing +comparisons rather than bit-wise operations. +@end defmac + +The term ``nails'' comes from finger or toe nails, which are at the ends of a +limb (arm or leg). ``numb'' is short for number, but is also how the +developers felt after trying for a long time to come up with sensible names +for these things. + +In the future (the distant future most likely) a non-zero nail might be +permitted, giving non-unique representations for numbers in a limb vector. +This would help vector processors since carries would only ever need to +propagate one or two limbs. + + +@node Random Number Functions, Formatted Output, Low-level Functions, Top +@chapter Random Number Functions +@cindex Random number functions + +Sequences of pseudo-random numbers in GMP are generated using a variable of +type @code{gmp_randstate_t}, which holds an algorithm selection and a current +state. Such a variable must be initialized by a call to one of the +@code{gmp_randinit} functions, and can be seeded with one of the +@code{gmp_randseed} functions. + +The functions actually generating random numbers are described in @ref{Integer +Random Numbers}, and @ref{Miscellaneous Float Functions}. + +The older style random number functions don't accept a @code{gmp_randstate_t} +parameter but instead share a global variable of that type. They use a +default algorithm and are currently not seeded (though perhaps that will +change in the future). The new functions accepting a @code{gmp_randstate_t} +are recommended for applications that care about randomness. + +@menu +* Random State Initialization:: +* Random State Seeding:: +* Random State Miscellaneous:: +@end menu + +@node Random State Initialization, Random State Seeding, Random Number Functions, Random Number Functions +@section Random State Initialization +@cindex Random number state +@cindex Initialization functions + +@deftypefun void gmp_randinit_default (gmp_randstate_t @var{state}) +Initialize @var{state} with a default algorithm. This will be a compromise +between speed and randomness, and is recommended for applications with no +special requirements. Currently this is @code{gmp_randinit_mt}. +@end deftypefun + +@deftypefun void gmp_randinit_mt (gmp_randstate_t @var{state}) +@cindex Mersenne twister random numbers +Initialize @var{state} for a Mersenne Twister algorithm. This algorithm is +fast and has good randomness properties. +@end deftypefun + +@deftypefun void gmp_randinit_lc_2exp (gmp_randstate_t @var{state}, const mpz_t @var{a}, @w{unsigned long @var{c}}, @w{mp_bitcnt_t @var{m2exp}}) +@cindex Linear congruential random numbers +Initialize @var{state} with a linear congruential algorithm @m{X = (@var{a}X + +@var{c}) @bmod 2^{m2exp}, X = (@var{a}*X + @var{c}) mod 2^@var{m2exp}}. + +The low bits of @math{X} in this algorithm are not very random. The least +significant bit will have a period no more than 2, and the second bit no more +than 4, etc. For this reason only the high half of each @math{X} is actually +used. + +When a random number of more than @math{@var{m2exp}/2} bits is to be +generated, multiple iterations of the recurrence are used and the results +concatenated. +@end deftypefun + +@deftypefun int gmp_randinit_lc_2exp_size (gmp_randstate_t @var{state}, mp_bitcnt_t @var{size}) +@cindex Linear congruential random numbers +Initialize @var{state} for a linear congruential algorithm as per +@code{gmp_randinit_lc_2exp}. @var{a}, @var{c} and @var{m2exp} are selected +from a table, chosen so that @var{size} bits (or more) of each @math{X} will +be used, i.e.@: @math{@var{m2exp}/2 @ge{} @var{size}}. + +If successful the return value is non-zero. If @var{size} is bigger than the +table data provides then the return value is zero. The maximum @var{size} +currently supported is 128. +@end deftypefun + +@deftypefun void gmp_randinit_set (gmp_randstate_t @var{rop}, gmp_randstate_t @var{op}) +Initialize @var{rop} with a copy of the algorithm and state from @var{op}. +@end deftypefun + +@c Although gmp_randinit, gmp_errno and related constants are obsolete, we +@c still put @findex entries for them, since they're still documented and +@c someone might be looking them up when perusing old application code. + +@deftypefun void gmp_randinit (gmp_randstate_t @var{state}, @w{gmp_randalg_t @var{alg}}, @dots{}) +@strong{This function is obsolete.} + +@findex GMP_RAND_ALG_LC +@findex GMP_RAND_ALG_DEFAULT +Initialize @var{state} with an algorithm selected by @var{alg}. The only +choice is @code{GMP_RAND_ALG_LC}, which is @code{gmp_randinit_lc_2exp_size} +described above. A third parameter of type @code{unsigned long} is required, +this is the @var{size} for that function. @code{GMP_RAND_ALG_DEFAULT} and 0 +are the same as @code{GMP_RAND_ALG_LC}. + +@c For reference, this is the only place gmp_errno has been documented, and +@c due to being non thread safe we won't be adding to its uses. +@findex gmp_errno +@findex GMP_ERROR_UNSUPPORTED_ARGUMENT +@findex GMP_ERROR_INVALID_ARGUMENT +@code{gmp_randinit} sets bits in the global variable @code{gmp_errno} to +indicate an error. @code{GMP_ERROR_UNSUPPORTED_ARGUMENT} if @var{alg} is +unsupported, or @code{GMP_ERROR_INVALID_ARGUMENT} if the @var{size} parameter +is too big. It may be noted this error reporting is not thread safe (a good +reason to use @code{gmp_randinit_lc_2exp_size} instead). +@end deftypefun + +@deftypefun void gmp_randclear (gmp_randstate_t @var{state}) +Free all memory occupied by @var{state}. +@end deftypefun + + +@node Random State Seeding, Random State Miscellaneous, Random State Initialization, Random Number Functions +@section Random State Seeding +@cindex Random number seeding +@cindex Seeding random numbers + +@deftypefun void gmp_randseed (gmp_randstate_t @var{state}, const mpz_t @var{seed}) +@deftypefunx void gmp_randseed_ui (gmp_randstate_t @var{state}, @w{unsigned long int @var{seed}}) +Set an initial seed value into @var{state}. + +The size of a seed determines how many different sequences of random numbers +it's possible to generate. The ``quality'' of the seed is the randomness +of a given seed compared to the previous seed used, and this affects the +randomness of separate number sequences. The method for choosing a seed is +critical if the generated numbers are to be used for important applications, +such as generating cryptographic keys. + +Traditionally the system time has been used to seed, but care needs to be +taken with this. If an application seeds often and the resolution of the +system clock is low, then the same sequence of numbers might be repeated. +Also, the system time is quite easy to guess, so if unpredictability is +required then it should definitely not be the only source for the seed value. +On some systems there's a special device @file{/dev/random} which provides +random data better suited for use as a seed. +@end deftypefun + + +@node Random State Miscellaneous, , Random State Seeding, Random Number Functions +@section Random State Miscellaneous + +@deftypefun {unsigned long} gmp_urandomb_ui (gmp_randstate_t @var{state}, unsigned long @var{n}) +Return a uniformly distributed random number of @var{n} bits, i.e.@: in the +range 0 to @m{2^n-1,2^@var{n}-1} inclusive. @var{n} must be less than or +equal to the number of bits in an @code{unsigned long}. +@end deftypefun + +@deftypefun {unsigned long} gmp_urandomm_ui (gmp_randstate_t @var{state}, unsigned long @var{n}) +Return a uniformly distributed random number in the range 0 to +@math{@var{n}-1}, inclusive. +@end deftypefun + + +@node Formatted Output, Formatted Input, Random Number Functions, Top +@chapter Formatted Output +@cindex Formatted output +@cindex @code{printf} formatted output + +@menu +* Formatted Output Strings:: +* Formatted Output Functions:: +* C++ Formatted Output:: +@end menu + +@node Formatted Output Strings, Formatted Output Functions, Formatted Output, Formatted Output +@section Format Strings + +@code{gmp_printf} and friends accept format strings similar to the standard C +@code{printf} (@pxref{Formatted Output,, Formatted Output, libc, The GNU C +Library Reference Manual}). A format specification is of the form + +@example +% [flags] [width] [.[precision]] [type] conv +@end example + +GMP adds types @samp{Z}, @samp{Q} and @samp{F} for @code{mpz_t}, @code{mpq_t} +and @code{mpf_t} respectively, @samp{M} for @code{mp_limb_t}, and @samp{N} for +an @code{mp_limb_t} array. @samp{Z}, @samp{Q}, @samp{M} and @samp{N} behave +like integers. @samp{Q} will print a @samp{/} and a denominator, if needed. +@samp{F} behaves like a float. For example, + +@example +mpz_t z; +gmp_printf ("%s is an mpz %Zd\n", "here", z); + +mpq_t q; +gmp_printf ("a hex rational: %#40Qx\n", q); + +mpf_t f; +int n; +gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n); + +mp_limb_t l; +gmp_printf ("limb %Mu\n", l); + +const mp_limb_t *ptr; +mp_size_t size; +gmp_printf ("limb array %Nx\n", ptr, size); +@end example + +For @samp{N} the limbs are expected least significant first, as per the +@code{mpn} functions (@pxref{Low-level Functions}). A negative size can be +given to print the value as a negative. + +All the standard C @code{printf} types behave the same as the C library +@code{printf}, and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are simply +handed to @code{printf} and only the GMP extensions handled directly. + +The flags accepted are as follows. GLIBC style @nisamp{'} is only for the +standard C types (not the GMP types), and only if the C library supports it. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{0} @tab pad with zeros (rather than spaces) +@item @nicode{#} @tab show the base with @samp{0x}, @samp{0X} or @samp{0} +@item @nicode{+} @tab always show a sign +@item (space) @tab show a space or a @samp{-} sign +@item @nicode{'} @tab group digits, GLIBC style (not GMP types) +@end multitable +@end quotation + +The optional width and precision can be given as a number within the format +string, or as a @samp{*} to take an extra parameter of type @code{int}, the +same as the standard @code{printf}. + +The standard types accepted are as follows. @samp{h} and @samp{l} are +portable, the rest will depend on the compiler (or include files) for the type +and the C library for the output. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{h} @tab @nicode{short} +@item @nicode{hh} @tab @nicode{char} +@item @nicode{j} @tab @nicode{intmax_t} or @nicode{uintmax_t} +@item @nicode{l} @tab @nicode{long} or @nicode{wchar_t} +@item @nicode{ll} @tab @nicode{long long} +@item @nicode{L} @tab @nicode{long double} +@item @nicode{q} @tab @nicode{quad_t} or @nicode{u_quad_t} +@item @nicode{t} @tab @nicode{ptrdiff_t} +@item @nicode{z} @tab @nicode{size_t} +@end multitable +@end quotation + +@noindent +The GMP types are + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{F} @tab @nicode{mpf_t}, float conversions +@item @nicode{Q} @tab @nicode{mpq_t}, integer conversions +@item @nicode{M} @tab @nicode{mp_limb_t}, integer conversions +@item @nicode{N} @tab @nicode{mp_limb_t} array, integer conversions +@item @nicode{Z} @tab @nicode{mpz_t}, integer conversions +@end multitable +@end quotation + +The conversions accepted are as follows. @samp{a} and @samp{A} are always +supported for @code{mpf_t} but depend on the C library for standard C float +types. @samp{m} and @samp{p} depend on the C library. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{a} @nicode{A} @tab hex floats, C99 style +@item @nicode{c} @tab character +@item @nicode{d} @tab decimal integer +@item @nicode{e} @nicode{E} @tab scientific format float +@item @nicode{f} @tab fixed point float +@item @nicode{i} @tab same as @nicode{d} +@item @nicode{g} @nicode{G} @tab fixed or scientific float +@item @nicode{m} @tab @code{strerror} string, GLIBC style +@item @nicode{n} @tab store characters written so far +@item @nicode{o} @tab octal integer +@item @nicode{p} @tab pointer +@item @nicode{s} @tab string +@item @nicode{u} @tab unsigned integer +@item @nicode{x} @nicode{X} @tab hex integer +@end multitable +@end quotation + +@samp{o}, @samp{x} and @samp{X} are unsigned for the standard C types, but for +types @samp{Z}, @samp{Q} and @samp{N} they are signed. @samp{u} is not +meaningful for @samp{Z}, @samp{Q} and @samp{N}. + +@samp{M} is a proxy for the C library @samp{l} or @samp{L}, according to the +size of @code{mp_limb_t}. Unsigned conversions will be usual, but a signed +conversion can be used and will interpret the value as a two's complement +negative. + +@samp{n} can be used with any type, even the GMP types. + +Other types or conversions that might be accepted by the C library +@code{printf} cannot be used through @code{gmp_printf}, this includes for +instance extensions registered with GLIBC @code{register_printf_function}. +Also currently there's no support for POSIX @samp{$} style numbered arguments +(perhaps this will be added in the future). + +The precision field has its usual meaning for integer @samp{Z} and float +@samp{F} types, but is currently undefined for @samp{Q} and should not be used +with that. + +@code{mpf_t} conversions only ever generate as many digits as can be +accurately represented by the operand, the same as @code{mpf_get_str} does. +Zeros will be used if necessary to pad to the requested precision. This +happens even for an @samp{f} conversion of an @code{mpf_t} which is an +integer, for instance @math{2^@W{1024}} in an @code{mpf_t} of 128 bits +precision will only produce about 40 digits, then pad with zeros to the +decimal point. An empty precision field like @samp{%.Fe} or @samp{%.Ff} can +be used to specifically request just the significant digits. Without any dot +and thus no precision field, a precision value of 6 will be used. Note that +these rules mean that @samp{%Ff}, @samp{%.Ff}, and @samp{%.0Ff} will all be +different. + +The decimal point character (or string) is taken from the current locale +settings on systems which provide @code{localeconv} (@pxref{Locales,, Locales +and Internationalization, libc, The GNU C Library Reference Manual}). The C +library will normally do the same for standard float output. + +The format string is only interpreted as plain @code{char}s, multibyte +characters are not recognised. Perhaps this will change in the future. + + +@node Formatted Output Functions, C++ Formatted Output, Formatted Output Strings, Formatted Output +@section Functions +@cindex Output functions + +Each of the following functions is similar to the corresponding C library +function. The basic @code{printf} forms take a variable argument list. The +@code{vprintf} forms take an argument pointer, see @ref{Variadic Functions,, +Variadic Functions, libc, The GNU C Library Reference Manual}, or @samp{man 3 +va_start}. + +It should be emphasised that if a format string is invalid, or the arguments +don't match what the format specifies, then the behaviour of any of these +functions will be unpredictable. GCC format string checking is not available, +since it doesn't recognise the GMP extensions. + +The file based functions @code{gmp_printf} and @code{gmp_fprintf} will return +@math{-1} to indicate a write error. Output is not ``atomic'', so partial +output may be produced if a write error occurs. All the functions can return +@math{-1} if the C library @code{printf} variant in use returns @math{-1}, but +this shouldn't normally occur. + +@deftypefun int gmp_printf (const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vprintf (const char *@var{fmt}, va_list @var{ap}) +Print to the standard output @code{stdout}. Return the number of characters +written, or @math{-1} if an error occurred. +@end deftypefun + +@deftypefun int gmp_fprintf (FILE *@var{fp}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vfprintf (FILE *@var{fp}, const char *@var{fmt}, va_list @var{ap}) +Print to the stream @var{fp}. Return the number of characters written, or +@math{-1} if an error occurred. +@end deftypefun + +@deftypefun int gmp_sprintf (char *@var{buf}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vsprintf (char *@var{buf}, const char *@var{fmt}, va_list @var{ap}) +Form a null-terminated string in @var{buf}. Return the number of characters +written, excluding the terminating null. + +No overlap is permitted between the space at @var{buf} and the string +@var{fmt}. + +These functions are not recommended, since there's no protection against +exceeding the space available at @var{buf}. +@end deftypefun + +@deftypefun int gmp_snprintf (char *@var{buf}, size_t @var{size}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vsnprintf (char *@var{buf}, size_t @var{size}, const char *@var{fmt}, va_list @var{ap}) +Form a null-terminated string in @var{buf}. No more than @var{size} bytes +will be written. To get the full output, @var{size} must be enough for the +string and null-terminator. + +The return value is the total number of characters which ought to have been +produced, excluding the terminating null. If @math{@var{retval} @ge{} +@var{size}} then the actual output has been truncated to the first +@math{@var{size}-1} characters, and a null appended. + +No overlap is permitted between the region @{@var{buf},@var{size}@} and the +@var{fmt} string. + +Notice the return value is in ISO C99 @code{snprintf} style. This is so even +if the C library @code{vsnprintf} is the older GLIBC 2.0.x style. +@end deftypefun + +@deftypefun int gmp_asprintf (char **@var{pp}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vasprintf (char **@var{pp}, const char *@var{fmt}, va_list @var{ap}) +Form a null-terminated string in a block of memory obtained from the current +memory allocation function (@pxref{Custom Allocation}). The block will be the +size of the string and null-terminator. The address of the block is stored to +*@var{pp}. The return value is the number of characters produced, excluding +the null-terminator. + +Unlike the C library @code{asprintf}, @code{gmp_asprintf} doesn't return +@math{-1} if there's no more memory available, it lets the current allocation +function handle that. +@end deftypefun + +@deftypefun int gmp_obstack_printf (struct obstack *@var{ob}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_obstack_vprintf (struct obstack *@var{ob}, const char *@var{fmt}, va_list @var{ap}) +@cindex @code{obstack} output +Append to the current object in @var{ob}. The return value is the number of +characters written. A null-terminator is not written. + +@var{fmt} cannot be within the current object in @var{ob}, since that object +might move as it grows. + +These functions are available only when the C library provides the obstack +feature, which probably means only on GNU systems, see @ref{Obstacks,, +Obstacks, libc, The GNU C Library Reference Manual}. +@end deftypefun + + +@node C++ Formatted Output, , Formatted Output Functions, Formatted Output +@section C++ Formatted Output +@cindex C++ @code{ostream} output +@cindex @code{ostream} output + +The following functions are provided in @file{libgmpxx} (@pxref{Headers and +Libraries}), which is built if C++ support is enabled (@pxref{Build Options}). +Prototypes are available from @code{}. + +@deftypefun ostream& operator<< (ostream& @var{stream}, const mpz_t @var{op}) +Print @var{op} to @var{stream}, using its @code{ios} formatting settings. +@code{ios::width} is reset to 0 after output, the same as the standard +@code{ostream operator<<} routines do. + +In hex or octal, @var{op} is printed as a signed number, the same as for +decimal. This is unlike the standard @code{operator<<} routines on @code{int} +etc, which instead give two's complement. +@end deftypefun + +@deftypefun ostream& operator<< (ostream& @var{stream}, const mpq_t @var{op}) +Print @var{op} to @var{stream}, using its @code{ios} formatting settings. +@code{ios::width} is reset to 0 after output, the same as the standard +@code{ostream operator<<} routines do. + +Output will be a fraction like @samp{5/9}, or if the denominator is 1 then +just a plain integer like @samp{123}. + +In hex or octal, @var{op} is printed as a signed value, the same as for +decimal. If @code{ios::showbase} is set then a base indicator is shown on +both the numerator and denominator (if the denominator is required). +@end deftypefun + +@deftypefun ostream& operator<< (ostream& @var{stream}, const mpf_t @var{op}) +Print @var{op} to @var{stream}, using its @code{ios} formatting settings. +@code{ios::width} is reset to 0 after output, the same as the standard +@code{ostream operator<<} routines do. + +The decimal point follows the standard library float @code{operator<<}, which +on recent systems means the @code{std::locale} imbued on @var{stream}. + +Hex and octal are supported, unlike the standard @code{operator<<} on +@code{double}. The mantissa will be in hex or octal, the exponent will be in +decimal. For hex the exponent delimiter is an @samp{@@}. This is as per +@code{mpf_out_str}. + +@code{ios::showbase} is supported, and will put a base on the mantissa, for +example hex @samp{0x1.8} or @samp{0x0.8}, or octal @samp{01.4} or @samp{00.4}. +This last form is slightly strange, but at least differentiates itself from +decimal. +@end deftypefun + +These operators mean that GMP types can be printed in the usual C++ way, for +example, + +@example +mpz_t z; +int n; +... +cout << "iteration " << n << " value " << z << "\n"; +@end example + +But note that @code{ostream} output (and @code{istream} input, @pxref{C++ +Formatted Input}) is the only overloading available for the GMP types and that +for instance using @code{+} with an @code{mpz_t} will have unpredictable +results. For classes with overloading, see @ref{C++ Class Interface}. + + +@node Formatted Input, C++ Class Interface, Formatted Output, Top +@chapter Formatted Input +@cindex Formatted input +@cindex @code{scanf} formatted input + +@menu +* Formatted Input Strings:: +* Formatted Input Functions:: +* C++ Formatted Input:: +@end menu + + +@node Formatted Input Strings, Formatted Input Functions, Formatted Input, Formatted Input +@section Formatted Input Strings + +@code{gmp_scanf} and friends accept format strings similar to the standard C +@code{scanf} (@pxref{Formatted Input,, Formatted Input, libc, The GNU C +Library Reference Manual}). A format specification is of the form + +@example +% [flags] [width] [type] conv +@end example + +GMP adds types @samp{Z}, @samp{Q} and @samp{F} for @code{mpz_t}, @code{mpq_t} +and @code{mpf_t} respectively. @samp{Z} and @samp{Q} behave like integers. +@samp{Q} will read a @samp{/} and a denominator, if present. @samp{F} behaves +like a float. + +GMP variables don't require an @code{&} when passed to @code{gmp_scanf}, since +they're already ``call-by-reference''. For example, + +@example +/* to read say "a(5) = 1234" */ +int n; +mpz_t z; +gmp_scanf ("a(%d) = %Zd\n", &n, z); + +mpq_t q1, q2; +gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2); + +/* to read say "topleft (1.55,-2.66)" */ +mpf_t x, y; +char buf[32]; +gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y); +@end example + +All the standard C @code{scanf} types behave the same as in the C library +@code{scanf}, and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are simply +handed to @code{scanf} and only the GMP extensions handled directly. + +The flags accepted are as follows. @samp{a} and @samp{'} will depend on +support from the C library, and @samp{'} cannot be used with GMP types. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{*} @tab read but don't store +@item @nicode{a} @tab allocate a buffer (string conversions) +@item @nicode{'} @tab grouped digits, GLIBC style (not GMP types) +@end multitable +@end quotation + +The standard types accepted are as follows. @samp{h} and @samp{l} are +portable, the rest will depend on the compiler (or include files) for the type +and the C library for the input. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{h} @tab @nicode{short} +@item @nicode{hh} @tab @nicode{char} +@item @nicode{j} @tab @nicode{intmax_t} or @nicode{uintmax_t} +@item @nicode{l} @tab @nicode{long int}, @nicode{double} or @nicode{wchar_t} +@item @nicode{ll} @tab @nicode{long long} +@item @nicode{L} @tab @nicode{long double} +@item @nicode{q} @tab @nicode{quad_t} or @nicode{u_quad_t} +@item @nicode{t} @tab @nicode{ptrdiff_t} +@item @nicode{z} @tab @nicode{size_t} +@end multitable +@end quotation + +@noindent +The GMP types are + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{F} @tab @nicode{mpf_t}, float conversions +@item @nicode{Q} @tab @nicode{mpq_t}, integer conversions +@item @nicode{Z} @tab @nicode{mpz_t}, integer conversions +@end multitable +@end quotation + +The conversions accepted are as follows. @samp{p} and @samp{[} will depend on +support from the C library, the rest are standard. + +@quotation +@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item @nicode{c} @tab character or characters +@item @nicode{d} @tab decimal integer +@item @nicode{e} @nicode{E} @nicode{f} @nicode{g} @nicode{G} + @tab float +@item @nicode{i} @tab integer with base indicator +@item @nicode{n} @tab characters read so far +@item @nicode{o} @tab octal integer +@item @nicode{p} @tab pointer +@item @nicode{s} @tab string of non-whitespace characters +@item @nicode{u} @tab decimal integer +@item @nicode{x} @nicode{X} @tab hex integer +@item @nicode{[} @tab string of characters in a set +@end multitable +@end quotation + +@samp{e}, @samp{E}, @samp{f}, @samp{g} and @samp{G} are identical, they all +read either fixed point or scientific format, and either upper or lower case +@samp{e} for the exponent in scientific format. + +C99 style hex float format (@code{printf %a}, @pxref{Formatted Output +Strings}) is always accepted for @code{mpf_t}, but for the standard float +types it will depend on the C library. + +@samp{x} and @samp{X} are identical, both accept both upper and lower case +hexadecimal. + +@samp{o}, @samp{u}, @samp{x} and @samp{X} all read positive or negative +values. For the standard C types these are described as ``unsigned'' +conversions, but that merely affects certain overflow handling, negatives are +still allowed (per @code{strtoul}, @pxref{Parsing of Integers,, Parsing of +Integers, libc, The GNU C Library Reference Manual}). For GMP types there are +no overflows, so @samp{d} and @samp{u} are identical. + +@samp{Q} type reads the numerator and (optional) denominator as given. If the +value might not be in canonical form then @code{mpq_canonicalize} must be +called before using it in any calculations (@pxref{Rational Number +Functions}). + +@samp{Qi} will read a base specification separately for the numerator and +denominator. For example @samp{0x10/11} would be 16/11, whereas +@samp{0x10/0x11} would be 16/17. + +@samp{n} can be used with any of the types above, even the GMP types. +@samp{*} to suppress assignment is allowed, though in that case it would do +nothing at all. + +Other conversions or types that might be accepted by the C library +@code{scanf} cannot be used through @code{gmp_scanf}. + +Whitespace is read and discarded before a field, except for @samp{c} and +@samp{[} conversions. + +For float conversions, the decimal point character (or string) expected is +taken from the current locale settings on systems which provide +@code{localeconv} (@pxref{Locales,, Locales and Internationalization, libc, +The GNU C Library Reference Manual}). The C library will normally do the same +for standard float input. + +The format string is only interpreted as plain @code{char}s, multibyte +characters are not recognised. Perhaps this will change in the future. + + +@node Formatted Input Functions, C++ Formatted Input, Formatted Input Strings, Formatted Input +@section Formatted Input Functions +@cindex Input functions + +Each of the following functions is similar to the corresponding C library +function. The plain @code{scanf} forms take a variable argument list. The +@code{vscanf} forms take an argument pointer, see @ref{Variadic Functions,, +Variadic Functions, libc, The GNU C Library Reference Manual}, or @samp{man 3 +va_start}. + +It should be emphasised that if a format string is invalid, or the arguments +don't match what the format specifies, then the behaviour of any of these +functions will be unpredictable. GCC format string checking is not available, +since it doesn't recognise the GMP extensions. + +No overlap is permitted between the @var{fmt} string and any of the results +produced. + +@deftypefun int gmp_scanf (const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vscanf (const char *@var{fmt}, va_list @var{ap}) +Read from the standard input @code{stdin}. +@end deftypefun + +@deftypefun int gmp_fscanf (FILE *@var{fp}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vfscanf (FILE *@var{fp}, const char *@var{fmt}, va_list @var{ap}) +Read from the stream @var{fp}. +@end deftypefun + +@deftypefun int gmp_sscanf (const char *@var{s}, const char *@var{fmt}, @dots{}) +@deftypefunx int gmp_vsscanf (const char *@var{s}, const char *@var{fmt}, va_list @var{ap}) +Read from a null-terminated string @var{s}. +@end deftypefun + +The return value from each of these functions is the same as the standard C99 +@code{scanf}, namely the number of fields successfully parsed and stored. +@samp{%n} fields and fields read but suppressed by @samp{*} don't count +towards the return value. + +If end of input (or a file error) is reached before a character for a field or +a literal, and if no previous non-suppressed fields have matched, then the +return value is @code{EOF} instead of 0. A whitespace character in the format +string is only an optional match and doesn't induce an @code{EOF} in this +fashion. Leading whitespace read and discarded for a field don't count as +characters for that field. + +For the GMP types, input parsing follows C99 rules, namely one character of +lookahead is used and characters are read while they continue to meet the +format requirements. If this doesn't provide a complete number then the +function terminates, with that field not stored nor counted towards the return +value. For instance with @code{mpf_t} an input @samp{1.23e-XYZ} would be read +up to the @samp{X} and that character pushed back since it's not a digit. The +string @samp{1.23e-} would then be considered invalid since an @samp{e} must +be followed by at least one digit. + +For the standard C types, in the current implementation GMP calls the C +library @code{scanf} functions, which might have looser rules about what +constitutes a valid input. + +Note that @code{gmp_sscanf} is the same as @code{gmp_fscanf} and only does one +character of lookahead when parsing. Although clearly it could look at its +entire input, it is deliberately made identical to @code{gmp_fscanf}, the same +way C99 @code{sscanf} is the same as @code{fscanf}. + + +@node C++ Formatted Input, , Formatted Input Functions, Formatted Input +@section C++ Formatted Input +@cindex C++ @code{istream} input +@cindex @code{istream} input + +The following functions are provided in @file{libgmpxx} (@pxref{Headers and +Libraries}), which is built only if C++ support is enabled (@pxref{Build +Options}). Prototypes are available from @code{}. + +@deftypefun istream& operator>> (istream& @var{stream}, mpz_t @var{rop}) +Read @var{rop} from @var{stream}, using its @code{ios} formatting settings. +@end deftypefun + +@deftypefun istream& operator>> (istream& @var{stream}, mpq_t @var{rop}) +An integer like @samp{123} will be read, or a fraction like @samp{5/9}. No +whitespace is allowed around the @samp{/}. If the fraction is not in +canonical form then @code{mpq_canonicalize} must be called (@pxref{Rational +Number Functions}) before operating on it. + +As per integer input, an @samp{0} or @samp{0x} base indicator is read when +none of @code{ios::dec}, @code{ios::oct} or @code{ios::hex} are set. This is +done separately for numerator and denominator, so that for instance +@samp{0x10/11} is @math{16/11} and @samp{0x10/0x11} is @math{16/17}. +@end deftypefun + +@deftypefun istream& operator>> (istream& @var{stream}, mpf_t @var{rop}) +Read @var{rop} from @var{stream}, using its @code{ios} formatting settings. + +Hex or octal floats are not supported, but might be in the future, or perhaps +it's best to accept only what the standard float @code{operator>>} does. +@end deftypefun + +Note that digit grouping specified by the @code{istream} locale is currently +not accepted. Perhaps this will change in the future. + +@sp 1 +These operators mean that GMP types can be read in the usual C++ way, for +example, + +@example +mpz_t z; +... +cin >> z; +@end example + +But note that @code{istream} input (and @code{ostream} output, @pxref{C++ +Formatted Output}) is the only overloading available for the GMP types and +that for instance using @code{+} with an @code{mpz_t} will have unpredictable +results. For classes with overloading, see @ref{C++ Class Interface}. + + + +@node C++ Class Interface, Custom Allocation, Formatted Input, Top +@chapter C++ Class Interface +@cindex C++ interface + +This chapter describes the C++ class based interface to GMP. + +All GMP C language types and functions can be used in C++ programs, since +@file{gmp.h} has @code{extern "C"} qualifiers, but the class interface offers +overloaded functions and operators which may be more convenient. + +Due to the implementation of this interface, a reasonably recent C++ compiler +is required, one supporting namespaces, partial specialization of templates +and member templates. + +@strong{Everything described in this chapter is to be considered preliminary +and might be subject to incompatible changes if some unforeseen difficulty +reveals itself.} + +@menu +* C++ Interface General:: +* C++ Interface Integers:: +* C++ Interface Rationals:: +* C++ Interface Floats:: +* C++ Interface Random Numbers:: +* C++ Interface Limitations:: +@end menu + + +@node C++ Interface General, C++ Interface Integers, C++ Class Interface, C++ Class Interface +@section C++ Interface General + +@noindent +All the C++ classes and functions are available with + +@cindex @code{gmpxx.h} +@example +#include +@end example + +Programs should be linked with the @file{libgmpxx} and @file{libgmp} +libraries. For example, + +@example +g++ mycxxprog.cc -lgmpxx -lgmp +@end example + +@noindent +The classes defined are + +@deftp Class mpz_class +@deftpx Class mpq_class +@deftpx Class mpf_class +@end deftp + +The standard operators and various standard functions are overloaded to allow +arithmetic with these classes. For example, + +@example +int +main (void) +@{ + mpz_class a, b, c; + + a = 1234; + b = "-5678"; + c = a+b; + cout << "sum is " << c << "\n"; + cout << "absolute value is " << abs(c) << "\n"; + + return 0; +@} +@end example + +An important feature of the implementation is that an expression like +@code{a=b+c} results in a single call to the corresponding @code{mpz_add}, +without using a temporary for the @code{b+c} part. Expressions which by their +nature imply intermediate values, like @code{a=b*c+d*e}, still use temporaries +though. + +The classes can be freely intermixed in expressions, as can the classes and +the standard types @code{long}, @code{unsigned long} and @code{double}. +Smaller types like @code{int} or @code{float} can also be intermixed, since +C++ will promote them. + +Note that @code{bool} is not accepted directly, but must be explicitly cast to +an @code{int} first. This is because C++ will automatically convert any +pointer to a @code{bool}, so if GMP accepted @code{bool} it would make all +sorts of invalid class and pointer combinations compile but almost certainly +not do anything sensible. + +Conversions back from the classes to standard C++ types aren't done +automatically, instead member functions like @code{get_si} are provided (see +the following sections for details). + +Also there are no automatic conversions from the classes to the corresponding +GMP C types, instead a reference to the underlying C object can be obtained +with the following functions, + +@deftypefun mpz_t mpz_class::get_mpz_t () +@deftypefunx mpq_t mpq_class::get_mpq_t () +@deftypefunx mpf_t mpf_class::get_mpf_t () +@end deftypefun + +These can be used to call a C function which doesn't have a C++ class +interface. For example to set @code{a} to the GCD of @code{b} and @code{c}, + +@example +mpz_class a, b, c; +... +mpz_gcd (a.get_mpz_t(), b.get_mpz_t(), c.get_mpz_t()); +@end example + +In the other direction, a class can be initialized from the corresponding GMP +C type, or assigned to if an explicit constructor is used. In both cases this +makes a copy of the value, it doesn't create any sort of association. For +example, + +@example +mpz_t z; +// ... init and calculate z ... +mpz_class x(z); +mpz_class y; +y = mpz_class (z); +@end example + +There are no namespace setups in @file{gmpxx.h}, all types and functions are +simply put into the global namespace. This is what @file{gmp.h} has done in +the past, and continues to do for compatibility. The extras provided by +@file{gmpxx.h} follow GMP naming conventions and are unlikely to clash with +anything. + + +@node C++ Interface Integers, C++ Interface Rationals, C++ Interface General, C++ Class Interface +@section C++ Interface Integers + +@deftypefun {} mpz_class::mpz_class (type @var{n}) +Construct an @code{mpz_class}. All the standard C++ types may be used, except +@code{long long} and @code{long double}, and all the GMP C++ classes can be +used, although conversions from @code{mpq_class} and @code{mpf_class} are +@code{explicit}. Any necessary conversion follows the corresponding C +function, for example @code{double} follows @code{mpz_set_d} +(@pxref{Assigning Integers}). +@end deftypefun + +@deftypefun explicit mpz_class::mpz_class (const mpz_t @var{z}) +Construct an @code{mpz_class} from an @code{mpz_t}. The value in @var{z} is +copied into the new @code{mpz_class}, there won't be any permanent association +between it and @var{z}. +@end deftypefun + +@deftypefun explicit mpz_class::mpz_class (const char *@var{s}, int @var{base} = 0) +@deftypefunx explicit mpz_class::mpz_class (const string& @var{s}, int @var{base} = 0) +Construct an @code{mpz_class} converted from a string using @code{mpz_set_str} +(@pxref{Assigning Integers}). + +If the string is not a valid integer, an @code{std::invalid_argument} +exception is thrown. The same applies to @code{operator=}. +@end deftypefun + +@deftypefun mpz_class operator"" _mpz (const char *@var{str}) +With C++11 compilers, integers can be constructed with the syntax +@code{123_mpz} which is equivalent to @code{mpz_class("123")}. +@end deftypefun + +@deftypefun mpz_class operator/ (mpz_class @var{a}, mpz_class @var{d}) +@deftypefunx mpz_class operator% (mpz_class @var{a}, mpz_class @var{d}) +Divisions involving @code{mpz_class} round towards zero, as per the +@code{mpz_tdiv_q} and @code{mpz_tdiv_r} functions (@pxref{Integer Division}). +This is the same as the C99 @code{/} and @code{%} operators. + +The @code{mpz_fdiv@dots{}} or @code{mpz_cdiv@dots{}} functions can always be called +directly if desired. For example, + +@example +mpz_class q, a, d; +... +mpz_fdiv_q (q.get_mpz_t(), a.get_mpz_t(), d.get_mpz_t()); +@end example +@end deftypefun + +@deftypefun mpz_class abs (mpz_class @var{op}) +@deftypefunx int cmp (mpz_class @var{op1}, type @var{op2}) +@deftypefunx int cmp (type @var{op1}, mpz_class @var{op2}) +@maybepagebreak +@deftypefunx bool mpz_class::fits_sint_p (void) +@deftypefunx bool mpz_class::fits_slong_p (void) +@deftypefunx bool mpz_class::fits_sshort_p (void) +@maybepagebreak +@deftypefunx bool mpz_class::fits_uint_p (void) +@deftypefunx bool mpz_class::fits_ulong_p (void) +@deftypefunx bool mpz_class::fits_ushort_p (void) +@maybepagebreak +@deftypefunx double mpz_class::get_d (void) +@deftypefunx long mpz_class::get_si (void) +@deftypefunx string mpz_class::get_str (int @var{base} = 10) +@deftypefunx {unsigned long} mpz_class::get_ui (void) +@maybepagebreak +@deftypefunx int mpz_class::set_str (const char *@var{str}, int @var{base}) +@deftypefunx int mpz_class::set_str (const string& @var{str}, int @var{base}) +@deftypefunx int sgn (mpz_class @var{op}) +@deftypefunx mpz_class sqrt (mpz_class @var{op}) +@maybepagebreak +@deftypefunx mpz_class gcd (mpz_class @var{op1}, mpz_class @var{op2}) +@deftypefunx mpz_class lcm (mpz_class @var{op1}, mpz_class @var{op2}) +@deftypefunx mpz_class mpz_class::factorial (type @var{op}) +@deftypefunx mpz_class factorial (mpz_class @var{op}) +@deftypefunx mpz_class mpz_class::primorial (type @var{op}) +@deftypefunx mpz_class primorial (mpz_class @var{op}) +@deftypefunx mpz_class mpz_class::fibonacci (type @var{op}) +@deftypefunx mpz_class fibonacci (mpz_class @var{op}) +@maybepagebreak +@deftypefunx void mpz_class::swap (mpz_class& @var{op}) +@deftypefunx void swap (mpz_class& @var{op1}, mpz_class& @var{op2}) +These functions provide a C++ class interface to the corresponding GMP C +routines. Calling @code{factorial} or @code{primorial} on a negative number +is undefined. + +@code{cmp} can be used with any of the classes or the standard C++ types, +except @code{long long} and @code{long double}. +@end deftypefun + +@sp 1 +Overloaded operators for combinations of @code{mpz_class} and @code{double} +are provided for completeness, but it should be noted that if the given +@code{double} is not an integer then the way any rounding is done is currently +unspecified. The rounding might take place at the start, in the middle, or at +the end of the operation, and it might change in the future. + +Conversions between @code{mpz_class} and @code{double}, however, are defined +to follow the corresponding C functions @code{mpz_get_d} and @code{mpz_set_d}. +And comparisons are always made exactly, as per @code{mpz_cmp_d}. + + +@node C++ Interface Rationals, C++ Interface Floats, C++ Interface Integers, C++ Class Interface +@section C++ Interface Rationals + +In all the following constructors, if a fraction is given then it should be in +canonical form, or if not then @code{mpq_class::canonicalize} called. + +@deftypefun {} mpq_class::mpq_class (type @var{op}) +@deftypefunx {} mpq_class::mpq_class (integer @var{num}, integer @var{den}) +Construct an @code{mpq_class}. The initial value can be a single value of any +type (conversion from @code{mpf_class} is @code{explicit}), or a pair of +integers (@code{mpz_class} or standard C++ integer types) representing a +fraction, except that @code{long long} and @code{long double} are not +supported. For example, + +@example +mpq_class q (99); +mpq_class q (1.75); +mpq_class q (1, 3); +@end example +@end deftypefun + +@deftypefun explicit mpq_class::mpq_class (const mpq_t @var{q}) +Construct an @code{mpq_class} from an @code{mpq_t}. The value in @var{q} is +copied into the new @code{mpq_class}, there won't be any permanent association +between it and @var{q}. +@end deftypefun + +@deftypefun explicit mpq_class::mpq_class (const char *@var{s}, int @var{base} = 0) +@deftypefunx explicit mpq_class::mpq_class (const string& @var{s}, int @var{base} = 0) +Construct an @code{mpq_class} converted from a string using @code{mpq_set_str} +(@pxref{Initializing Rationals}). + +If the string is not a valid rational, an @code{std::invalid_argument} +exception is thrown. The same applies to @code{operator=}. +@end deftypefun + +@deftypefun mpq_class operator"" _mpq (const char *@var{str}) +With C++11 compilers, integral rationals can be constructed with the syntax +@code{123_mpq} which is equivalent to @code{mpq_class(123_mpz)}. Other +rationals can be built as @code{-1_mpq/2} or @code{0xb_mpq/123456_mpz}. +@end deftypefun + +@deftypefun void mpq_class::canonicalize () +Put an @code{mpq_class} into canonical form, as per @ref{Rational Number +Functions}. All arithmetic operators require their operands in canonical +form, and will return results in canonical form. +@end deftypefun + +@deftypefun mpq_class abs (mpq_class @var{op}) +@deftypefunx int cmp (mpq_class @var{op1}, type @var{op2}) +@deftypefunx int cmp (type @var{op1}, mpq_class @var{op2}) +@maybepagebreak +@deftypefunx double mpq_class::get_d (void) +@deftypefunx string mpq_class::get_str (int @var{base} = 10) +@maybepagebreak +@deftypefunx int mpq_class::set_str (const char *@var{str}, int @var{base}) +@deftypefunx int mpq_class::set_str (const string& @var{str}, int @var{base}) +@deftypefunx int sgn (mpq_class @var{op}) +@maybepagebreak +@deftypefunx void mpq_class::swap (mpq_class& @var{op}) +@deftypefunx void swap (mpq_class& @var{op1}, mpq_class& @var{op2}) +These functions provide a C++ class interface to the corresponding GMP C +routines. + +@code{cmp} can be used with any of the classes or the standard C++ types, +except @code{long long} and @code{long double}. +@end deftypefun + +@deftypefun {mpz_class&} mpq_class::get_num () +@deftypefunx {mpz_class&} mpq_class::get_den () +Get a reference to an @code{mpz_class} which is the numerator or denominator +of an @code{mpq_class}. This can be used both for read and write access. If +the object returned is modified, it modifies the original @code{mpq_class}. + +If direct manipulation might produce a non-canonical value, then +@code{mpq_class::canonicalize} must be called before further operations. +@end deftypefun + +@deftypefun mpz_t mpq_class::get_num_mpz_t () +@deftypefunx mpz_t mpq_class::get_den_mpz_t () +Get a reference to the underlying @code{mpz_t} numerator or denominator of an +@code{mpq_class}. This can be passed to C functions expecting an +@code{mpz_t}. Any modifications made to the @code{mpz_t} will modify the +original @code{mpq_class}. + +If direct manipulation might produce a non-canonical value, then +@code{mpq_class::canonicalize} must be called before further operations. +@end deftypefun + +@deftypefun istream& operator>> (istream& @var{stream}, mpq_class& @var{rop}); +Read @var{rop} from @var{stream}, using its @code{ios} formatting settings, +the same as @code{mpq_t operator>>} (@pxref{C++ Formatted Input}). + +If the @var{rop} read might not be in canonical form then +@code{mpq_class::canonicalize} must be called. +@end deftypefun + + +@node C++ Interface Floats, C++ Interface Random Numbers, C++ Interface Rationals, C++ Class Interface +@section C++ Interface Floats + +When an expression requires the use of temporary intermediate @code{mpf_class} +values, like @code{f=g*h+x*y}, those temporaries will have the same precision +as the destination @code{f}. Explicit constructors can be used if this +doesn't suit. + +@deftypefun {} mpf_class::mpf_class (type @var{op}) +@deftypefunx {} mpf_class::mpf_class (type @var{op}, mp_bitcnt_t @var{prec}) +Construct an @code{mpf_class}. Any standard C++ type can be used, except +@code{long long} and @code{long double}, and any of the GMP C++ classes can be +used. + +If @var{prec} is given, the initial precision is that value, in bits. If +@var{prec} is not given, then the initial precision is determined by the type +of @var{op} given. An @code{mpz_class}, @code{mpq_class}, or C++ +builtin type will give the default @code{mpf} precision (@pxref{Initializing +Floats}). An @code{mpf_class} or expression will give the precision of that +value. The precision of a binary expression is the higher of the two +operands. + +@example +mpf_class f(1.5); // default precision +mpf_class f(1.5, 500); // 500 bits (at least) +mpf_class f(x); // precision of x +mpf_class f(abs(x)); // precision of x +mpf_class f(-g, 1000); // 1000 bits (at least) +mpf_class f(x+y); // greater of precisions of x and y +@end example +@end deftypefun + +@deftypefun explicit mpf_class::mpf_class (const mpf_t @var{f}) +@deftypefunx {} mpf_class::mpf_class (const mpf_t @var{f}, mp_bitcnt_t @var{prec}) +Construct an @code{mpf_class} from an @code{mpf_t}. The value in @var{f} is +copied into the new @code{mpf_class}, there won't be any permanent association +between it and @var{f}. + +If @var{prec} is given, the initial precision is that value, in bits. If +@var{prec} is not given, then the initial precision is that of @var{f}. +@end deftypefun + +@deftypefun explicit mpf_class::mpf_class (const char *@var{s}) +@deftypefunx {} mpf_class::mpf_class (const char *@var{s}, mp_bitcnt_t @var{prec}, int @var{base} = 0) +@deftypefunx explicit mpf_class::mpf_class (const string& @var{s}) +@deftypefunx {} mpf_class::mpf_class (const string& @var{s}, mp_bitcnt_t @var{prec}, int @var{base} = 0) +Construct an @code{mpf_class} converted from a string using @code{mpf_set_str} +(@pxref{Assigning Floats}). If @var{prec} is given, the initial precision is +that value, in bits. If not, the default @code{mpf} precision +(@pxref{Initializing Floats}) is used. + +If the string is not a valid float, an @code{std::invalid_argument} exception +is thrown. The same applies to @code{operator=}. +@end deftypefun + +@deftypefun mpf_class operator"" _mpf (const char *@var{str}) +With C++11 compilers, floats can be constructed with the syntax +@code{1.23e-1_mpf} which is equivalent to @code{mpf_class("1.23e-1")}. +@end deftypefun + +@deftypefun {mpf_class&} mpf_class::operator= (type @var{op}) +Convert and store the given @var{op} value to an @code{mpf_class} object. The +same types are accepted as for the constructors above. + +Note that @code{operator=} only stores a new value, it doesn't copy or change +the precision of the destination, instead the value is truncated if necessary. +This is the same as @code{mpf_set} etc. Note in particular this means for +@code{mpf_class} a copy constructor is not the same as a default constructor +plus assignment. + +@example +mpf_class x (y); // x created with precision of y + +mpf_class x; // x created with default precision +x = y; // value truncated to that precision +@end example + +Applications using templated code may need to be careful about the assumptions +the code makes in this area, when working with @code{mpf_class} values of +various different or non-default precisions. For instance implementations of +the standard @code{complex} template have been seen in both styles above, +though of course @code{complex} is normally only actually specified for use +with the builtin float types. +@end deftypefun + +@deftypefun mpf_class abs (mpf_class @var{op}) +@deftypefunx mpf_class ceil (mpf_class @var{op}) +@deftypefunx int cmp (mpf_class @var{op1}, type @var{op2}) +@deftypefunx int cmp (type @var{op1}, mpf_class @var{op2}) +@maybepagebreak +@deftypefunx bool mpf_class::fits_sint_p (void) +@deftypefunx bool mpf_class::fits_slong_p (void) +@deftypefunx bool mpf_class::fits_sshort_p (void) +@maybepagebreak +@deftypefunx bool mpf_class::fits_uint_p (void) +@deftypefunx bool mpf_class::fits_ulong_p (void) +@deftypefunx bool mpf_class::fits_ushort_p (void) +@maybepagebreak +@deftypefunx mpf_class floor (mpf_class @var{op}) +@deftypefunx mpf_class hypot (mpf_class @var{op1}, mpf_class @var{op2}) +@maybepagebreak +@deftypefunx double mpf_class::get_d (void) +@deftypefunx long mpf_class::get_si (void) +@deftypefunx string mpf_class::get_str (mp_exp_t& @var{exp}, int @var{base} = 10, size_t @var{digits} = 0) +@deftypefunx {unsigned long} mpf_class::get_ui (void) +@maybepagebreak +@deftypefunx int mpf_class::set_str (const char *@var{str}, int @var{base}) +@deftypefunx int mpf_class::set_str (const string& @var{str}, int @var{base}) +@deftypefunx int sgn (mpf_class @var{op}) +@deftypefunx mpf_class sqrt (mpf_class @var{op}) +@maybepagebreak +@deftypefunx void mpf_class::swap (mpf_class& @var{op}) +@deftypefunx void swap (mpf_class& @var{op1}, mpf_class& @var{op2}) +@deftypefunx mpf_class trunc (mpf_class @var{op}) +These functions provide a C++ class interface to the corresponding GMP C +routines. + +@code{cmp} can be used with any of the classes or the standard C++ types, +except @code{long long} and @code{long double}. + +The accuracy provided by @code{hypot} is not currently guaranteed. +@end deftypefun + +@deftypefun {mp_bitcnt_t} mpf_class::get_prec () +@deftypefunx void mpf_class::set_prec (mp_bitcnt_t @var{prec}) +@deftypefunx void mpf_class::set_prec_raw (mp_bitcnt_t @var{prec}) +Get or set the current precision of an @code{mpf_class}. + +The restrictions described for @code{mpf_set_prec_raw} (@pxref{Initializing +Floats}) apply to @code{mpf_class::set_prec_raw}. Note in particular that the +@code{mpf_class} must be restored to its allocated precision before being +destroyed. This must be done by application code, there's no automatic +mechanism for it. +@end deftypefun + + +@node C++ Interface Random Numbers, C++ Interface Limitations, C++ Interface Floats, C++ Class Interface +@section C++ Interface Random Numbers + +@deftp Class gmp_randclass +The C++ class interface to the GMP random number functions uses +@code{gmp_randclass} to hold an algorithm selection and current state, as per +@code{gmp_randstate_t}. +@end deftp + +@deftypefun {} gmp_randclass::gmp_randclass (void (*@var{randinit}) (gmp_randstate_t, @dots{}), @dots{}) +Construct a @code{gmp_randclass}, using a call to the given @var{randinit} +function (@pxref{Random State Initialization}). The arguments expected are +the same as @var{randinit}, but with @code{mpz_class} instead of @code{mpz_t}. +For example, + +@example +gmp_randclass r1 (gmp_randinit_default); +gmp_randclass r2 (gmp_randinit_lc_2exp_size, 32); +gmp_randclass r3 (gmp_randinit_lc_2exp, a, c, m2exp); +gmp_randclass r4 (gmp_randinit_mt); +@end example + +@code{gmp_randinit_lc_2exp_size} will fail if the size requested is too big, +an @code{std::length_error} exception is thrown in that case. +@end deftypefun + +@deftypefun {} gmp_randclass::gmp_randclass (gmp_randalg_t @var{alg}, @dots{}) +Construct a @code{gmp_randclass} using the same parameters as +@code{gmp_randinit} (@pxref{Random State Initialization}). This function is +obsolete and the above @var{randinit} style should be preferred. +@end deftypefun + +@deftypefun void gmp_randclass::seed (unsigned long int @var{s}) +@deftypefunx void gmp_randclass::seed (mpz_class @var{s}) +Seed a random number generator. See @pxref{Random Number Functions}, for how +to choose a good seed. +@end deftypefun + +@deftypefun mpz_class gmp_randclass::get_z_bits (mp_bitcnt_t @var{bits}) +@deftypefunx mpz_class gmp_randclass::get_z_bits (mpz_class @var{bits}) +Generate a random integer with a specified number of bits. +@end deftypefun + +@deftypefun mpz_class gmp_randclass::get_z_range (mpz_class @var{n}) +Generate a random integer in the range 0 to @math{@var{n}-1} inclusive. +@end deftypefun + +@deftypefun mpf_class gmp_randclass::get_f () +@deftypefunx mpf_class gmp_randclass::get_f (mp_bitcnt_t @var{prec}) +Generate a random float @var{f} in the range @math{0 <= @var{f} < 1}. @var{f} +will be to @var{prec} bits precision, or if @var{prec} is not given then to +the precision of the destination. For example, + +@example +gmp_randclass r; +... +mpf_class f (0, 512); // 512 bits precision +f = r.get_f(); // random number, 512 bits +@end example +@end deftypefun + + + +@node C++ Interface Limitations, , C++ Interface Random Numbers, C++ Class Interface +@section C++ Interface Limitations + +@table @asis +@item @code{mpq_class} and Templated Reading +A generic piece of template code probably won't know that @code{mpq_class} +requires a @code{canonicalize} call if inputs read with @code{operator>>} +might be non-canonical. This can lead to incorrect results. + +@code{operator>>} behaves as it does for reasons of efficiency. A +canonicalize can be quite time consuming on large operands, and is best +avoided if it's not necessary. + +But this potential difficulty reduces the usefulness of @code{mpq_class}. +Perhaps a mechanism to tell @code{operator>>} what to do will be adopted in +the future, maybe a preprocessor define, a global flag, or an @code{ios} flag +pressed into service. Or maybe, at the risk of inconsistency, the +@code{mpq_class} @code{operator>>} could canonicalize and leave @code{mpq_t} +@code{operator>>} not doing so, for use on those occasions when that's +acceptable. Send feedback or alternate ideas to @email{gmp-bugs@@gmplib.org}. + +@item Subclassing +Subclassing the GMP C++ classes works, but is not currently recommended. + +Expressions involving subclasses resolve correctly (or seem to), but in normal +C++ fashion the subclass doesn't inherit constructors and assignments. +There's many of those in the GMP classes, and a good way to reestablish them +in a subclass is not yet provided. + +@item Templated Expressions +A subtle difficulty exists when using expressions together with +application-defined template functions. Consider the following, with @code{T} +intended to be some numeric type, + +@example +template +T fun (const T &, const T &); +@end example + +@noindent +When used with, say, plain @code{mpz_class} variables, it works fine: @code{T} +is resolved as @code{mpz_class}. + +@example +mpz_class f(1), g(2); +fun (f, g); // Good +@end example + +@noindent +But when one of the arguments is an expression, it doesn't work. + +@example +mpz_class f(1), g(2), h(3); +fun (f, g+h); // Bad +@end example + +This is because @code{g+h} ends up being a certain expression template type +internal to @code{gmpxx.h}, which the C++ template resolution rules are unable +to automatically convert to @code{mpz_class}. The workaround is simply to add +an explicit cast. + +@example +mpz_class f(1), g(2), h(3); +fun (f, mpz_class(g+h)); // Good +@end example + +Similarly, within @code{fun} it may be necessary to cast an expression to type +@code{T} when calling a templated @code{fun2}. + +@example +template +void fun (T f, T g) +@{ + fun2 (f, f+g); // Bad +@} + +template +void fun (T f, T g) +@{ + fun2 (f, T(f+g)); // Good +@} +@end example + +@item C++11 +C++11 provides several new ways in which types can be inferred: @code{auto}, +@code{decltype}, etc. While they can be very convenient, they don't mix well +with expression templates. In this example, the addition is performed twice, +as if we had defined @code{sum} as a macro. + +@example +mpz_class z = 33; +auto sum = z + z; +mpz_class prod = sum * sum; +@end example + +This other example may crash, though some compilers might make it look like +it is working, because the expression @code{z+z} goes out of scope before it +is evaluated. + +@example +mpz_class z = 33; +auto sum = z + z + z; +mpz_class prod = sum * 2; +@end example + +It is thus strongly recommended to avoid @code{auto} anywhere a GMP C++ +expression may appear. +@end table + + +@node Custom Allocation, Language Bindings, C++ Class Interface, Top +@comment node-name, next, previous, up +@chapter Custom Allocation +@cindex Custom allocation +@cindex Memory allocation +@cindex Allocation of memory + +By default GMP uses @code{malloc}, @code{realloc} and @code{free} for memory +allocation, and if they fail GMP prints a message to the standard error output +and terminates the program. + +Alternate functions can be specified, to allocate memory in a different way or +to have a different error action on running out of memory. + +@deftypefun void mp_set_memory_functions (@* void *(*@var{alloc_func_ptr}) (size_t), @* void *(*@var{realloc_func_ptr}) (void *, size_t, size_t), @* void (*@var{free_func_ptr}) (void *, size_t)) +Replace the current allocation functions from the arguments. If an argument +is @code{NULL}, the corresponding default function is used. + +These functions will be used for all memory allocation done by GMP, apart from +temporary space from @code{alloca} if that function is available and GMP is +configured to use it (@pxref{Build Options}). + +@strong{Be sure to call @code{mp_set_memory_functions} only when there are no +active GMP objects allocated using the previous memory functions! Usually +that means calling it before any other GMP function.} +@end deftypefun + +The functions supplied should fit the following declarations: + +@deftypevr Function {void *} allocate_function (size_t @var{alloc_size}) +Return a pointer to newly allocated space with at least @var{alloc_size} +bytes. +@end deftypevr + +@deftypevr Function {void *} reallocate_function (void *@var{ptr}, size_t @var{old_size}, size_t @var{new_size}) +Resize a previously allocated block @var{ptr} of @var{old_size} bytes to be +@var{new_size} bytes. + +The block may be moved if necessary or if desired, and in that case the +smaller of @var{old_size} and @var{new_size} bytes must be copied to the new +location. The return value is a pointer to the resized block, that being the +new location if moved or just @var{ptr} if not. + +@var{ptr} is never @code{NULL}, it's always a previously allocated block. +@var{new_size} may be bigger or smaller than @var{old_size}. +@end deftypevr + +@deftypevr Function void free_function (void *@var{ptr}, size_t @var{size}) +De-allocate the space pointed to by @var{ptr}. + +@var{ptr} is never @code{NULL}, it's always a previously allocated block of +@var{size} bytes. +@end deftypevr + +A @dfn{byte} here means the unit used by the @code{sizeof} operator. + +The @var{reallocate_function} parameter @var{old_size} and the +@var{free_function} parameter @var{size} are passed for convenience, but of +course they can be ignored if not needed by an implementation. The default +functions using @code{malloc} and friends for instance don't use them. + +No error return is allowed from any of these functions, if they return then +they must have performed the specified operation. In particular note that +@var{allocate_function} or @var{reallocate_function} mustn't return +@code{NULL}. + +Getting a different fatal error action is a good use for custom allocation +functions, for example giving a graphical dialog rather than the default print +to @code{stderr}. How much is possible when genuinely out of memory is +another question though. + +There's currently no defined way for the allocation functions to recover from +an error such as out of memory, they must terminate program execution. A +@code{longjmp} or throwing a C++ exception will have undefined results. This +may change in the future. + +GMP may use allocated blocks to hold pointers to other allocated blocks. This +will limit the assumptions a conservative garbage collection scheme can make. + +Since the default GMP allocation uses @code{malloc} and friends, those +functions will be linked in even if the first thing a program does is an +@code{mp_set_memory_functions}. It's necessary to change the GMP sources if +this is a problem. + +@sp 1 +@deftypefun void mp_get_memory_functions (@* void *(**@var{alloc_func_ptr}) (size_t), @* void *(**@var{realloc_func_ptr}) (void *, size_t, size_t), @* void (**@var{free_func_ptr}) (void *, size_t)) +Get the current allocation functions, storing function pointers to the +locations given by the arguments. If an argument is @code{NULL}, that +function pointer is not stored. + +@need 1000 +For example, to get just the current free function, + +@example +void (*freefunc) (void *, size_t); + +mp_get_memory_functions (NULL, NULL, &freefunc); +@end example +@end deftypefun + +@node Language Bindings, Algorithms, Custom Allocation, Top +@chapter Language Bindings +@cindex Language bindings +@cindex Other languages + +The following packages and projects offer access to GMP from languages other +than C, though perhaps with varying levels of functionality and efficiency. + +@c @spaceuref{U} is the same as @uref{U}, but with a couple of extra spaces +@c in tex, just to separate the URL from the preceding text a bit. +@iftex +@macro spaceuref {U} +@ @ @uref{\U\} +@end macro +@end iftex +@ifnottex +@macro spaceuref {U} +@uref{\U\} +@end macro +@end ifnottex + +@sp 1 +@table @asis +@item C++ +@itemize @bullet +@item +GMP C++ class interface, @pxref{C++ Class Interface} @* Straightforward +interface, expression templates to eliminate temporaries. +@item +ALP @spaceuref{https://www-sop.inria.fr/saga/logiciels/ALP/} @* Linear algebra and +polynomials using templates. +@item +CLN @spaceuref{https://www.ginac.de/CLN/} @* High level classes for arithmetic. +@item +Linbox @spaceuref{http://www.linalg.org/} @* Sparse vectors and matrices. +@item +NTL @spaceuref{http://www.shoup.net/ntl/} @* A C++ number theory library. +@end itemize + +@c @item D +@c @itemize @bullet +@c @item +@c gmp-d @spaceuref{http://home.comcast.net/~benhinkle/gmp-d/} +@c @end itemize + +@item Eiffel +@itemize @bullet +@item +Eiffelroom @spaceuref{http://www.eiffelroom.org/node/442} +@end itemize + +@c @item Fortran +@c @itemize @bullet +@c @item +@c Omni F77 @spaceuref{http://phase.hpcc.jp/Omni/home.html} @* Arbitrary +@c precision floats. +@c @end itemize + +@item Haskell +@itemize @bullet +@item +Glasgow Haskell Compiler @spaceuref{https://www.haskell.org/ghc/} +@end itemize + +@item Java +@itemize @bullet +@item +Kaffe @spaceuref{https://github.com/kaffe/kaffe} +@end itemize + +@item Lisp +@itemize @bullet +@item +GNU Common Lisp @spaceuref{https://www.gnu.org/software/gcl/gcl.html} +@item +Librep @spaceuref{http://librep.sourceforge.net/} +@item +@c FIXME: When there's a stable release with gmp support, just refer to it +@c rather than bothering to talk about betas. +XEmacs (21.5.18 beta and up) @spaceuref{https://www.xemacs.org} @* Optional +big integers, rationals and floats using GMP. +@end itemize + +@item ML +@itemize @bullet +@item +MLton compiler @spaceuref{http://mlton.org/} +@end itemize + +@item Objective Caml +@itemize @bullet +@item +MLGMP @spaceuref{https://opam.ocaml.org/packages/mlgmp/} +@item +Numerix @spaceuref{http://pauillac.inria.fr/~quercia/} @* Optionally using +GMP. +@end itemize + +@item Oz +@itemize @bullet +@item +Mozart @spaceuref{https://mozart.github.io/} +@end itemize + +@item Pascal +@itemize @bullet +@item +GNU Pascal Compiler @spaceuref{http://www.gnu-pascal.de/} @* GMP unit. +@item +Numerix @spaceuref{http://pauillac.inria.fr/~quercia/} @* For Free Pascal, +optionally using GMP. +@end itemize + +@item Perl +@itemize @bullet +@item +GMP module, see @file{demos/perl} in the GMP sources (@pxref{Demonstration +Programs}). +@item +Math::GMP @spaceuref{https://www.cpan.org/} @* Compatible with Math::BigInt, but +not as many functions as the GMP module above. +@item +Math::BigInt::GMP @spaceuref{https://www.cpan.org/} @* Plug Math::GMP into +normal Math::BigInt operations. +@end itemize + +@need 1000 +@item Pike +@itemize @bullet +@item +pikempz module in the standard distribution, @uref{https://pike.lysator.liu.se/} +@end itemize + +@need 500 +@item Prolog +@itemize @bullet +@item +SWI Prolog @spaceuref{http://www.swi-prolog.org/} @* +Arbitrary precision floats. +@end itemize + +@item Python +@itemize @bullet +@item +GMPY @uref{https://code.google.com/p/gmpy/} +@end itemize + +@item Ruby +@itemize @bullet +@item +@uref{https://rubygems.org/gems/gmp} +@end itemize + +@item Scheme +@itemize @bullet +@item +GNU Guile @spaceuref{https://www.gnu.org/software/guile/guile.html} +@item +RScheme @spaceuref{https://www.rscheme.org/} +@item +STklos @spaceuref{http://www.stklos.net/} +@c +@c For reference, MzScheme uses some of gmp, but (as of version 205) it only +@c has copies of some of the generic C code, and we don't consider that a +@c language binding to gmp. +@c +@end itemize + +@item Smalltalk +@itemize @bullet +@item +GNU Smalltalk @spaceuref{http://smalltalk.gnu.org/} +@end itemize + +@item Other +@itemize @bullet +@item +Axiom @uref{https://savannah.nongnu.org/projects/axiom} @* Computer algebra +using GCL. +@item +DrGenius @spaceuref{http://drgenius.seul.org/} @* Geometry system and +mathematical programming language. +@item +GiNaC @spaceuref{httsp://www.ginac.de/} @* C++ computer algebra using CLN. +@item +GOO @spaceuref{https://www.eecs.berkeley.edu/~jrb/goo/} @* Dynamic object oriented +language. +@item +Maxima @uref{https://www.ma.utexas.edu/users/wfs/maxima.html} @* Macsyma +computer algebra using GCL. +@c @item +@c Q @spaceuref{http://q-lang.sourceforge.net/} @* Equational programming system. +@item +Regina @spaceuref{http://regina.sourceforge.net/} @* Topological calculator. +@item +Yacas @spaceuref{http://yacas.sourceforge.net} @* Yet another computer algebra system. +@end itemize + +@end table + + +@node Algorithms, Internals, Language Bindings, Top +@chapter Algorithms +@cindex Algorithms + +This chapter is an introduction to some of the algorithms used for various GMP +operations. The code is likely to be hard to understand without knowing +something about the algorithms. + +Some GMP internals are mentioned, but applications that expect to be +compatible with future GMP releases should take care to use only the +documented functions. + +@menu +* Multiplication Algorithms:: +* Division Algorithms:: +* Greatest Common Divisor Algorithms:: +* Powering Algorithms:: +* Root Extraction Algorithms:: +* Radix Conversion Algorithms:: +* Other Algorithms:: +* Assembly Coding:: +@end menu + + +@node Multiplication Algorithms, Division Algorithms, Algorithms, Algorithms +@section Multiplication +@cindex Multiplication algorithms + +N@cross{}N limb multiplications and squares are done using one of seven +algorithms, as the size N increases. + +@quotation +@multitable {KaratsubaMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item Algorithm @tab Threshold +@item Basecase @tab (none) +@item Karatsuba @tab @code{MUL_TOOM22_THRESHOLD} +@item Toom-3 @tab @code{MUL_TOOM33_THRESHOLD} +@item Toom-4 @tab @code{MUL_TOOM44_THRESHOLD} +@item Toom-6.5 @tab @code{MUL_TOOM6H_THRESHOLD} +@item Toom-8.5 @tab @code{MUL_TOOM8H_THRESHOLD} +@item FFT @tab @code{MUL_FFT_THRESHOLD} +@end multitable +@end quotation + +Similarly for squaring, with the @code{SQR} thresholds. + +N@cross{}M multiplications of operands with different sizes above +@code{MUL_TOOM22_THRESHOLD} are currently done by special Toom-inspired +algorithms or directly with FFT, depending on operand size (@pxref{Unbalanced +Multiplication}). + +@menu +* Basecase Multiplication:: +* Karatsuba Multiplication:: +* Toom 3-Way Multiplication:: +* Toom 4-Way Multiplication:: +* Higher degree Toom'n'half:: +* FFT Multiplication:: +* Other Multiplication:: +* Unbalanced Multiplication:: +@end menu + + +@node Basecase Multiplication, Karatsuba Multiplication, Multiplication Algorithms, Multiplication Algorithms +@subsection Basecase Multiplication + +Basecase N@cross{}M multiplication is a straightforward rectangular set of +cross-products, the same as long multiplication done by hand and for that +reason sometimes known as the schoolbook or grammar school method. This is an +@m{O(NM),O(N*M)} algorithm. See Knuth section 4.3.1 algorithm M +(@pxref{References}), and the @file{mpn/generic/mul_basecase.c} code. + +Assembly implementations of @code{mpn_mul_basecase} are essentially the same +as the generic C code, but have all the usual assembly tricks and +obscurities introduced for speed. + +A square can be done in roughly half the time of a multiply, by using the fact +that the cross products above and below the diagonal are the same. A triangle +of products below the diagonal is formed, doubled (left shift by one bit), and +then the products on the diagonal added. This can be seen in +@file{mpn/generic/sqr_basecase.c}. Again the assembly implementations take +essentially the same approach. + +@tex +\def\GMPline#1#2#3#4#5#6{% + \hbox {% + \vrule height 2.5ex depth 1ex + \hbox to 2em {\hfil{#2}\hfil}% + \vrule \hbox to 2em {\hfil{#3}\hfil}% + \vrule \hbox to 2em {\hfil{#4}\hfil}% + \vrule \hbox to 2em {\hfil{#5}\hfil}% + \vrule \hbox to 2em {\hfil{#6}\hfil}% + \vrule}} +\GMPdisplay{ + \hbox{% + \vbox{% + \hbox to 1.5em {\vrule height 2.5ex depth 1ex width 0pt}% + \hbox {\vrule height 2.5ex depth 1ex width 0pt u0\hfil}% + \hbox {\vrule height 2.5ex depth 1ex width 0pt u1\hfil}% + \hbox {\vrule height 2.5ex depth 1ex width 0pt u2\hfil}% + \hbox {\vrule height 2.5ex depth 1ex width 0pt u3\hfil}% + \hbox {\vrule height 2.5ex depth 1ex width 0pt u4\hfil}% + \vfill}% + \vbox{% + \hbox{% + \hbox to 2em {\hfil u0\hfil}% + \hbox to 2em {\hfil u1\hfil}% + \hbox to 2em {\hfil u2\hfil}% + \hbox to 2em {\hfil u3\hfil}% + \hbox to 2em {\hfil u4\hfil}}% + \vskip 0.7ex + \hrule + \GMPline{u0}{d}{}{}{}{}% + \hrule + \GMPline{u1}{}{d}{}{}{}% + \hrule + \GMPline{u2}{}{}{d}{}{}% + \hrule + \GMPline{u3}{}{}{}{d}{}% + \hrule + \GMPline{u4}{}{}{}{}{d}% + \hrule}}} +@end tex +@ifnottex +@example +@group + u0 u1 u2 u3 u4 + +---+---+---+---+---+ +u0 | d | | | | | + +---+---+---+---+---+ +u1 | | d | | | | + +---+---+---+---+---+ +u2 | | | d | | | + +---+---+---+---+---+ +u3 | | | | d | | + +---+---+---+---+---+ +u4 | | | | | d | + +---+---+---+---+---+ +@end group +@end example +@end ifnottex + +In practice squaring isn't a full 2@cross{} faster than multiplying, it's +usually around 1.5@cross{}. Less than 1.5@cross{} probably indicates +@code{mpn_sqr_basecase} wants improving on that CPU. + +On some CPUs @code{mpn_mul_basecase} can be faster than the generic C +@code{mpn_sqr_basecase} on some small sizes. @code{SQR_BASECASE_THRESHOLD} is +the size at which to use @code{mpn_sqr_basecase}, this will be zero if that +routine should be used always. + + +@node Karatsuba Multiplication, Toom 3-Way Multiplication, Basecase Multiplication, Multiplication Algorithms +@subsection Karatsuba Multiplication +@cindex Karatsuba multiplication + +The Karatsuba multiplication algorithm is described in Knuth section 4.3.3 +part A, and various other textbooks. A brief description is given here. + +The inputs @math{x} and @math{y} are treated as each split into two parts of +equal length (or the most significant part one limb shorter if N is odd). + +@tex +% GMPboxwidth used for all the multiplication pictures +\global\newdimen\GMPboxwidth \global\GMPboxwidth=5em +% GMPboxdepth and GMPboxheight are also used for the float pictures +\global\newdimen\GMPboxdepth \global\GMPboxdepth=1ex +\global\newdimen\GMPboxheight \global\GMPboxheight=2ex +\gdef\GMPvrule{\vrule height \GMPboxheight depth \GMPboxdepth} +\def\GMPbox#1#2{% + \vbox {% + \hrule + \hbox to 2\GMPboxwidth{% + \GMPvrule \hfil $#1$\hfil \vrule \hfil $#2$\hfil \vrule}% + \hrule}} +\GMPdisplay{% +\vbox{% + \hbox to 2\GMPboxwidth {high \hfil low} + \vskip 0.7ex + \GMPbox{x_1}{x_0} + \vskip 0.5ex + \GMPbox{y_1}{y_0} +}} +@end tex +@ifnottex +@example +@group + high low ++----------+----------+ +| x1 | x0 | ++----------+----------+ + ++----------+----------+ +| y1 | y0 | ++----------+----------+ +@end group +@end example +@end ifnottex + +Let @math{b} be the power of 2 where the split occurs, i.e.@: if @ms{x,0} is +@math{k} limbs (@ms{y,0} the same) then +@m{b=2\GMPraise{$k*$@code{mp\_bits\_per\_limb}}, b=2^(k*mp_bits_per_limb)}. +With that @m{x=x_1b+x_0,x=x1*b+x0} and @m{y=y_1b+y_0,y=y1*b+y0}, and the +following holds, + +@display +@m{xy = (b^2+b)x_1y_1 - b(x_1-x_0)(y_1-y_0) + (b+1)x_0y_0, + x*y = (b^2+b)*x1*y1 - b*(x1-x0)*(y1-y0) + (b+1)*x0*y0} +@end display + +This formula means doing only three multiplies of (N/2)@cross{}(N/2) limbs, +whereas a basecase multiply of N@cross{}N limbs is equivalent to four +multiplies of (N/2)@cross{}(N/2). The factors @math{(b^2+b)} etc represent +the positions where the three products must be added. + +@tex +\def\GMPboxA#1#2{% + \vbox{% + \hrule + \hbox{% + \GMPvrule + \hbox to 2\GMPboxwidth {\hfil\hbox{$#1$}\hfil}% + \vrule + \hbox to 2\GMPboxwidth {\hfil\hbox{$#2$}\hfil}% + \vrule} + \hrule}} +\def\GMPboxB#1#2{% + \hbox{% + \raise \GMPboxdepth \hbox to \GMPboxwidth {\hfil #1\hskip 0.5em}% + \vbox{% + \hrule + \hbox{% + \GMPvrule + \hbox to 2\GMPboxwidth {\hfil\hbox{$#2$}\hfil}% + \vrule}% + \hrule}}} +\GMPdisplay{% +\vbox{% + \hbox to 4\GMPboxwidth {high \hfil low} + \vskip 0.7ex + \GMPboxA{x_1y_1}{x_0y_0} + \vskip 0.5ex + \GMPboxB{$+$}{x_1y_1} + \vskip 0.5ex + \GMPboxB{$+$}{x_0y_0} + \vskip 0.5ex + \GMPboxB{$-$}{(x_1-x_0)(y_1-y_0)} +}} +@end tex +@ifnottex +@example +@group + high low ++--------+--------+ +--------+--------+ +| x1*y1 | | x0*y0 | ++--------+--------+ +--------+--------+ + +--------+--------+ + add | x1*y1 | + +--------+--------+ + +--------+--------+ + add | x0*y0 | + +--------+--------+ + +--------+--------+ + sub | (x1-x0)*(y1-y0) | + +--------+--------+ +@end group +@end example +@end ifnottex + +The term @m{(x_1-x_0)(y_1-y_0),(x1-x0)*(y1-y0)} is best calculated as an +absolute value, and the sign used to choose to add or subtract. Notice the +sum @m{\mathop{\rm high}(x_0y_0)+\mathop{\rm low}(x_1y_1), +high(x0*y0)+low(x1*y1)} occurs twice, so it's possible to do @m{5k,5*k} limb +additions, rather than @m{6k,6*k}, but in GMP extra function call overheads +outweigh the saving. + +Squaring is similar to multiplying, but with @math{x=y} the formula reduces to +an equivalent with three squares, + +@display +@m{x^2 = (b^2+b)x_1^2 - b(x_1-x_0)^2 + (b+1)x_0^2, + x^2 = (b^2+b)*x1^2 - b*(x1-x0)^2 + (b+1)*x0^2} +@end display + +The final result is accumulated from those three squares the same way as for +the three multiplies above. The middle term @m{(x_1-x_0)^2,(x1-x0)^2} is now +always positive. + +A similar formula for both multiplying and squaring can be constructed with a +middle term @m{(x_1+x_0)(y_1+y_0),(x1+x0)*(y1+y0)}. But those sums can exceed +@math{k} limbs, leading to more carry handling and additions than the form +above. + +Karatsuba multiplication is asymptotically an @math{O(N^@W{1.585})} algorithm, +the exponent being @m{\log3/\log2,log(3)/log(2)}, representing 3 multiplies +each @math{1/2} the size of the inputs. This is a big improvement over the +basecase multiply at @math{O(N^2)} and the advantage soon overcomes the extra +additions Karatsuba performs. @code{MUL_TOOM22_THRESHOLD} can be as little +as 10 limbs. The @code{SQR} threshold is usually about twice the @code{MUL}. + +The basecase algorithm will take a time of the form @m{M(N) = aN^2 + bN + c, +M(N) = a*N^2 + b*N + c} and the Karatsuba algorithm @m{K(N) = 3M(N/2) + dN + +e, K(N) = 3*M(N/2) + d*N + e}, which expands to @m{K(N) = {3\over4} aN^2 + +{3\over2} bN + 3c + dN + e, K(N) = 3/4*a*N^2 + 3/2*b*N + 3*c + d*N + e}. The +factor @m{3\over4, 3/4} for @math{a} means per-crossproduct speedups in the +basecase code will increase the threshold since they benefit @math{M(N)} more +than @math{K(N)}. And conversely the @m{3\over2, 3/2} for @math{b} means +linear style speedups of @math{b} will increase the threshold since they +benefit @math{K(N)} more than @math{M(N)}. The latter can be seen for +instance when adding an optimized @code{mpn_sqr_diagonal} to +@code{mpn_sqr_basecase}. Of course all speedups reduce total time, and in +that sense the algorithm thresholds are merely of academic interest. + + +@node Toom 3-Way Multiplication, Toom 4-Way Multiplication, Karatsuba Multiplication, Multiplication Algorithms +@subsection Toom 3-Way Multiplication +@cindex Toom multiplication + +The Karatsuba formula is the simplest case of a general approach to splitting +inputs that leads to both Toom and FFT algorithms. A description of +Toom can be found in Knuth section 4.3.3, with an example 3-way +calculation after Theorem A@. The 3-way form used in GMP is described here. + +The operands are each considered split into 3 pieces of equal length (or the +most significant part 1 or 2 limbs shorter than the other two). + +@tex +\def\GMPbox#1#2#3{% + \vbox{% + \hrule \vfil + \hbox to 3\GMPboxwidth {% + \GMPvrule + \hfil$#1$\hfil + \vrule + \hfil$#2$\hfil + \vrule + \hfil$#3$\hfil + \vrule}% + \vfil \hrule +}} +\GMPdisplay{% +\vbox{% + \hbox to 3\GMPboxwidth {high \hfil low} + \vskip 0.7ex + \GMPbox{x_2}{x_1}{x_0} + \vskip 0.5ex + \GMPbox{y_2}{y_1}{y_0} + \vskip 0.5ex +}} +@end tex +@ifnottex +@example +@group + high low ++----------+----------+----------+ +| x2 | x1 | x0 | ++----------+----------+----------+ + ++----------+----------+----------+ +| y2 | y1 | y0 | ++----------+----------+----------+ +@end group +@end example +@end ifnottex + +@noindent +These parts are treated as the coefficients of two polynomials + +@display +@group +@m{X(t) = x_2t^2 + x_1t + x_0, + X(t) = x2*t^2 + x1*t + x0} +@m{Y(t) = y_2t^2 + y_1t + y_0, + Y(t) = y2*t^2 + y1*t + y0} +@end group +@end display + +Let @math{b} equal the power of 2 which is the size of the @ms{x,0}, @ms{x,1}, +@ms{y,0} and @ms{y,1} pieces, i.e.@: if they're @math{k} limbs each then +@m{b=2\GMPraise{$k*$@code{mp\_bits\_per\_limb}}, b=2^(k*mp_bits_per_limb)}. +With this @math{x=X(b)} and @math{y=Y(b)}. + +Let a polynomial @m{W(t)=X(t)Y(t),W(t)=X(t)*Y(t)} and suppose its coefficients +are + +@display +@m{W(t) = w_4t^4 + w_3t^3 + w_2t^2 + w_1t + w_0, + W(t) = w4*t^4 + w3*t^3 + w2*t^2 + w1*t + w0} +@end display + +The @m{w_i,w[i]} are going to be determined, and when they are they'll give +the final result using @math{w=W(b)}, since +@m{xy=X(b)Y(b),x*y=X(b)*Y(b)=W(b)}. The coefficients will be roughly +@math{b^2} each, and the final @math{W(b)} will be an addition like this: + +@tex +\def\GMPbox#1#2{% + \moveright #1\GMPboxwidth + \vbox{% + \hrule + \hbox{% + \GMPvrule + \hbox to 2\GMPboxwidth {\hfil$#2$\hfil}% + \vrule}% + \hrule +}} +\GMPdisplay{% +\vbox{% + \hbox to 6\GMPboxwidth {high \hfil low}% + \vskip 0.7ex + \GMPbox{0}{w_4} + \vskip 0.5ex + \GMPbox{1}{w_3} + \vskip 0.5ex + \GMPbox{2}{w_2} + \vskip 0.5ex + \GMPbox{3}{w_1} + \vskip 0.5ex + \GMPbox{4}{w_0} +}} +@end tex +@ifnottex +@example +@group + high low ++-------+-------+ +| w4 | ++-------+-------+ + +--------+-------+ + | w3 | + +--------+-------+ + +--------+-------+ + | w2 | + +--------+-------+ + +--------+-------+ + | w1 | + +--------+-------+ + +-------+-------+ + | w0 | + +-------+-------+ +@end group +@end example +@end ifnottex + +The @m{w_i,w[i]} coefficients could be formed by a simple set of cross +products, like @m{w_4=x_2y_2,w4=x2*y2}, @m{w_3=x_2y_1+x_1y_2,w3=x2*y1+x1*y2}, +@m{w_2=x_2y_0+x_1y_1+x_0y_2,w2=x2*y0+x1*y1+x0*y2} etc, but this would need all +nine @m{x_iy_j,x[i]*y[j]} for @math{i,j=0,1,2}, and would be equivalent merely +to a basecase multiply. Instead the following approach is used. + +@math{X(t)} and @math{Y(t)} are evaluated and multiplied at 5 points, giving +values of @math{W(t)} at those points. In GMP the following points are used: + +@quotation +@multitable {@m{t=\infty,t=inf}M} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item Point @tab Value +@item @math{t=0} @tab @m{x_0y_0,x0 * y0}, which gives @ms{w,0} immediately +@item @math{t=1} @tab @m{(x_2+x_1+x_0)(y_2+y_1+y_0),(x2+x1+x0) * (y2+y1+y0)} +@item @math{t=-1} @tab @m{(x_2-x_1+x_0)(y_2-y_1+y_0),(x2-x1+x0) * (y2-y1+y0)} +@item @math{t=2} @tab @m{(4x_2+2x_1+x_0)(4y_2+2y_1+y_0),(4*x2+2*x1+x0) * (4*y2+2*y1+y0)} +@item @m{t=\infty,t=inf} @tab @m{x_2y_2,x2 * y2}, which gives @ms{w,4} immediately +@end multitable +@end quotation + +At @math{t=-1} the values can be negative and that's handled using the +absolute values and tracking the sign separately. At @m{t=\infty,t=inf} the +value is actually @m{\lim_{t\to\infty} {X(t)Y(t)\over t^4}, X(t)*Y(t)/t^4 in +the limit as t approaches infinity}, but it's much easier to think of as +simply @m{x_2y_2,x2*y2} giving @ms{w,4} immediately (much like +@m{x_0y_0,x0*y0} at @math{t=0} gives @ms{w,0} immediately). + +Each of the points substituted into +@m{W(t)=w_4t^4+\cdots+w_0,W(t)=w4*t^4+@dots{}+w0} gives a linear combination +of the @m{w_i,w[i]} coefficients, and the value of those combinations has just +been calculated. + +@tex +\GMPdisplay{% +$\matrix{% +W(0) & = & & & & & & & & & w_0 \cr +W(1) & = & w_4 & + & w_3 & + & w_2 & + & w_1 & + & w_0 \cr +W(-1) & = & w_4 & - & w_3 & + & w_2 & - & w_1 & + & w_0 \cr +W(2) & = & 16w_4 & + & 8w_3 & + & 4w_2 & + & 2w_1 & + & w_0 \cr +W(\infty) & = & w_4 \cr +}$} +@end tex +@ifnottex +@example +@group +W(0) = w0 +W(1) = w4 + w3 + w2 + w1 + w0 +W(-1) = w4 - w3 + w2 - w1 + w0 +W(2) = 16*w4 + 8*w3 + 4*w2 + 2*w1 + w0 +W(inf) = w4 +@end group +@end example +@end ifnottex + +This is a set of five equations in five unknowns, and some elementary linear +algebra quickly isolates each @m{w_i,w[i]}. This involves adding or +subtracting one @math{W(t)} value from another, and a couple of divisions by +powers of 2 and one division by 3, the latter using the special +@code{mpn_divexact_by3} (@pxref{Exact Division}). + +The conversion of @math{W(t)} values to the coefficients is interpolation. A +polynomial of degree 4 like @math{W(t)} is uniquely determined by values known +at 5 different points. The points are arbitrary and can be chosen to make the +linear equations come out with a convenient set of steps for quickly isolating +the @m{w_i,w[i]}. + +Squaring follows the same procedure as multiplication, but there's only one +@math{X(t)} and it's evaluated at the 5 points, and those values squared to +give values of @math{W(t)}. The interpolation is then identical, and in fact +the same @code{toom_interpolate_5pts} subroutine is used for both squaring and +multiplying. + +Toom-3 is asymptotically @math{O(N^@W{1.465})}, the exponent being +@m{\log5/\log3,log(5)/log(3)}, representing 5 recursive multiplies of 1/3 the +original size each. This is an improvement over Karatsuba at +@math{O(N^@W{1.585})}, though Toom does more work in the evaluation and +interpolation and so it only realizes its advantage above a certain size. + +Near the crossover between Toom-3 and Karatsuba there's generally a range of +sizes where the difference between the two is small. +@code{MUL_TOOM33_THRESHOLD} is a somewhat arbitrary point in that range and +successive runs of the tune program can give different values due to small +variations in measuring. A graph of time versus size for the two shows the +effect, see @file{tune/README}. + +At the fairly small sizes where the Toom-3 thresholds occur it's worth +remembering that the asymptotic behaviour for Karatsuba and Toom-3 can't be +expected to make accurate predictions, due of course to the big influence of +all sorts of overheads, and the fact that only a few recursions of each are +being performed. Even at large sizes there's a good chance machine dependent +effects like cache architecture will mean actual performance deviates from +what might be predicted. + +The formula given for the Karatsuba algorithm (@pxref{Karatsuba +Multiplication}) has an equivalent for Toom-3 involving only five multiplies, +but this would be complicated and unenlightening. + +An alternate view of Toom-3 can be found in Zuras (@pxref{References}), using +a vector to represent the @math{x} and @math{y} splits and a matrix +multiplication for the evaluation and interpolation stages. The matrix +inverses are not meant to be actually used, and they have elements with values +much greater than in fact arise in the interpolation steps. The diagram shown +for the 3-way is attractive, but again doesn't have to be implemented that way +and for example with a bit of rearrangement just one division by 6 can be +done. + + +@node Toom 4-Way Multiplication, Higher degree Toom'n'half, Toom 3-Way Multiplication, Multiplication Algorithms +@subsection Toom 4-Way Multiplication +@cindex Toom multiplication + +Karatsuba and Toom-3 split the operands into 2 and 3 coefficients, +respectively. Toom-4 analogously splits the operands into 4 coefficients. +Using the notation from the section on Toom-3 multiplication, we form two +polynomials: + +@display +@group +@m{X(t) = x_3t^3 + x_2t^2 + x_1t + x_0, + X(t) = x3*t^3 + x2*t^2 + x1*t + x0} +@m{Y(t) = y_3t^3 + y_2t^2 + y_1t + y_0, + Y(t) = y3*t^3 + y2*t^2 + y1*t + y0} +@end group +@end display + +@math{X(t)} and @math{Y(t)} are evaluated and multiplied at 7 points, giving +values of @math{W(t)} at those points. In GMP the following points are used, + +@quotation +@multitable {@m{t=-1/2,t=inf}M} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} +@item Point @tab Value +@item @math{t=0} @tab @m{x_0y_0,x0 * y0}, which gives @ms{w,0} immediately +@item @math{t=1/2} @tab @m{(x_3+2x_2+4x_1+8x_0)(y_3+2y_2+4y_1+8y_0),(x3+2*x2+4*x1+8*x0) * (y3+2*y2+4*y1+8*y0)} +@item @math{t=-1/2} @tab @m{(-x_3+2x_2-4x_1+8x_0)(-y_3+2y_2-4y_1+8y_0),(-x3+2*x2-4*x1+8*x0) * (-y3+2*y2-4*y1+8*y0)} +@item @math{t=1} @tab @m{(x_3+x_2+x_1+x_0)(y_3+y_2+y_1+y_0),(x3+x2+x1+x0) * (y3+y2+y1+y0)} +@item @math{t=-1} @tab @m{(-x_3+x_2-x_1+x_0)(-y_3+y_2-y_1+y_0),(-x3+x2-x1+x0) * (-y3+y2-y1+y0)} +@item @math{t=2} @tab @m{(8x_3+4x_2+2x_1+x_0)(8y_3+4y_2+2y_1+y_0),(8*x3+4*x2+2*x1+x0) * (8*y3+4*y2+2*y1+y0)} +@item @m{t=\infty,t=inf} @tab @m{x_3y_3,x3 * y3}, which gives @ms{w,6} immediately +@end multitable +@end quotation + +The number of additions and subtractions for Toom-4 is much larger than for Toom-3. +But several subexpressions occur multiple times, for example @m{x_2+x_0,x2+x0} occurs +for both @math{t=1} and @math{t=-1}. + +Toom-4 is asymptotically @math{O(N^@W{1.404})}, the exponent being +@m{\log7/\log4,log(7)/log(4)}, representing 7 recursive multiplies of 1/4 the +original size each. + + +@node Higher degree Toom'n'half, FFT Multiplication, Toom 4-Way Multiplication, Multiplication Algorithms +@subsection Higher degree Toom'n'half +@cindex Toom multiplication + +The Toom algorithms described above (@pxref{Toom 3-Way Multiplication}, +@pxref{Toom 4-Way Multiplication}) generalize to split into an arbitrary +number of pieces. In general a split of two equally long operands into +@math{r} pieces leads to evaluations and pointwise multiplications done at +@m{2r-1,2*r-1} points. To fully exploit symmetries it would be better to have +a multiple of 4 points, that's why for higher degree Toom'n'half is used. + +Toom'n'half means that the existence of one more piece is considered for a +single operand. It can be virtual, i.e. zero, or real, when the two operands +are not exactly balanced. By choosing an even @math{r}, +Toom-@m{r{1\over2},r+1/2} requires @math{2r} points, a multiple of four. + +The quadruplets of points include 0, @m{\infty,inf}, +1, @m{-1} and +@m{\pm2^i,+-2^i}, @m{\pm2^{-i},+-2^-i}. Each of them giving shortcuts for the +evaluation phase and for some steps in the interpolation phase. Further tricks +are used to reduce the memory footprint of the whole multiplication algorithm +to a memory buffer equal in size to the result of the product. + +Current GMP uses both Toom-6'n'half and Toom-8'n'half. + + +@node FFT Multiplication, Other Multiplication, Higher degree Toom'n'half, Multiplication Algorithms +@subsection FFT Multiplication +@cindex FFT multiplication +@cindex Fast Fourier Transform + +At large to very large sizes a Fermat style FFT multiplication is used, +following Sch@"onhage and Strassen (@pxref{References}). Descriptions of FFTs +in various forms can be found in many textbooks, for instance Knuth section +4.3.3 part C or Lipson chapter IX@. A brief description of the form used in +GMP is given here. + +The multiplication done is @m{xy \bmod 2^N+1, x*y mod 2^N+1}, for a given +@math{N}. A full product @m{xy,x*y} is obtained by choosing @m{N \ge +\mathop{\rm bits}(x)+\mathop{\rm bits}(y), N>=bits(x)+bits(y)} and padding +@math{x} and @math{y} with high zero limbs. The modular product is the native +form for the algorithm, so padding to get a full product is unavoidable. + +The algorithm follows a split, evaluate, pointwise multiply, interpolate and +combine similar to that described above for Karatsuba and Toom-3. A @math{k} +parameter controls the split, with an FFT-@math{k} splitting into @math{2^k} +pieces of @math{M=N/2^k} bits each. @math{N} must be a multiple of +@m{2^k\times@code{mp\_bits\_per\_limb}, (2^k)*@nicode{mp_bits_per_limb}} so +the split falls on limb boundaries, avoiding bit shifts in the split and +combine stages. + +The evaluations, pointwise multiplications, and interpolation are all done +modulo @m{2^{N'}+1, 2^N'+1} where @math{N'} is @math{2M+k+3} rounded up to a +multiple of @math{2^k} and of @code{mp_bits_per_limb}. The results of +interpolation will be the following negacyclic convolution of the input +pieces, and the choice of @math{N'} ensures these sums aren't truncated. +@tex +$$ w_n = \sum_{{i+j = b2^k+n}\atop{b=0,1}} (-1)^b x_i y_j $$ +@end tex +@ifnottex + +@example + --- + \ b +w[n] = / (-1) * x[i] * y[j] + --- + i+j==b*2^k+n + b=0,1 +@end example + +@end ifnottex +The points used for the evaluation are @math{g^i} for @math{i=0} to +@math{2^k-1} where @m{g=2^{2N'/2^k}, g=2^(2N'/2^k)}. @math{g} is a +@m{2^k,2^k'}th root of unity mod @m{2^{N'}+1,2^N'+1}, which produces necessary +cancellations at the interpolation stage, and it's also a power of 2 so the +fast Fourier transforms used for the evaluation and interpolation do only +shifts, adds and negations. + +The pointwise multiplications are done modulo @m{2^{N'}+1, 2^N'+1} and either +recurse into a further FFT or use a plain multiplication (Toom-3, Karatsuba or +basecase), whichever is optimal at the size @math{N'}. The interpolation is +an inverse fast Fourier transform. The resulting set of sums of @m{x_iy_j, +x[i]*y[j]} are added at appropriate offsets to give the final result. + +Squaring is the same, but @math{x} is the only input so it's one transform at +the evaluate stage and the pointwise multiplies are squares. The +interpolation is the same. + +For a mod @math{2^N+1} product, an FFT-@math{k} is an @m{O(N^{k/(k-1)}), +O(N^(k/(k-1)))} algorithm, the exponent representing @math{2^k} recursed +modular multiplies each @m{1/2^{k-1},1/2^(k-1)} the size of the original. +Each successive @math{k} is an asymptotic improvement, but overheads mean each +is only faster at bigger and bigger sizes. In the code, @code{MUL_FFT_TABLE} +and @code{SQR_FFT_TABLE} are the thresholds where each @math{k} is used. Each +new @math{k} effectively swaps some multiplying for some shifts, adds and +overheads. + +A mod @math{2^N+1} product can be formed with a normal +@math{N@cross{}N@rightarrow{}2N} bit multiply plus a subtraction, so an FFT +and Toom-3 etc can be compared directly. A @math{k=4} FFT at +@math{O(N^@W{1.333})} can be expected to be the first faster than Toom-3 at +@math{O(N^@W{1.465})}. In practice this is what's found, with +@code{MUL_FFT_MODF_THRESHOLD} and @code{SQR_FFT_MODF_THRESHOLD} being between +300 and 1000 limbs, depending on the CPU@. So far it's been found that only +very large FFTs recurse into pointwise multiplies above these sizes. + +When an FFT is to give a full product, the change of @math{N} to @math{2N} +doesn't alter the theoretical complexity for a given @math{k}, but for the +purposes of considering where an FFT might be first used it can be assumed +that the FFT is recursing into a normal multiply and that on that basis it's +doing @math{2^k} recursed multiplies each @m{1/2^{k-2},1/2^(k-2)} the size of +the inputs, making it @m{O(N^{k/(k-2)}), O(N^(k/(k-2)))}. This would mean +@math{k=7} at @math{O(N^@W{1.4})} would be the first FFT faster than Toom-3. +In practice @code{MUL_FFT_THRESHOLD} and @code{SQR_FFT_THRESHOLD} have been +found to be in the @math{k=8} range, somewhere between 3000 and 10000 limbs. + +The way @math{N} is split into @math{2^k} pieces and then @math{2M+k+3} is +rounded up to a multiple of @math{2^k} and @code{mp_bits_per_limb} means that +when @math{2^k@ge{}@nicode{mp\_bits\_per\_limb}} the effective @math{N} is a +multiple of @m{2^{2k-1},2^(2k-1)} bits. The @math{+k+3} means some values of +@math{N} just under such a multiple will be rounded to the next. The +complexity calculations above assume that a favourable size is used, meaning +one which isn't padded through rounding, and it's also assumed that the extra +@math{+k+3} bits are negligible at typical FFT sizes. + +The practical effect of the @m{2^{2k-1},2^(2k-1)} constraint is to introduce a +step-effect into measured speeds. For example @math{k=8} will round @math{N} +up to a multiple of 32768 bits, so for a 32-bit limb there'll be 512 limb +groups of sizes for which @code{mpn_mul_n} runs at the same speed. Or for +@math{k=9} groups of 2048 limbs, @math{k=10} groups of 8192 limbs, etc. In +practice it's been found each @math{k} is used at quite small multiples of its +size constraint and so the step effect is quite noticeable in a time versus +size graph. + +The threshold determinations currently measure at the mid-points of size +steps, but this is sub-optimal since at the start of a new step it can happen +that it's better to go back to the previous @math{k} for a while. Something +more sophisticated for @code{MUL_FFT_TABLE} and @code{SQR_FFT_TABLE} will be +needed. + + +@node Other Multiplication, Unbalanced Multiplication, FFT Multiplication, Multiplication Algorithms +@subsection Other Multiplication +@cindex Toom multiplication + +The Toom algorithms described above (@pxref{Toom 3-Way Multiplication}, +@pxref{Toom 4-Way Multiplication}) generalizes to split into an arbitrary +number of pieces, as per Knuth section 4.3.3 algorithm C@. This is not +currently used. The notes here are merely for interest. + +In general a split into @math{r+1} pieces is made, and evaluations and +pointwise multiplications done at @m{2r+1,2*r+1} points. A 4-way split does 7 +pointwise multiplies, 5-way does 9, etc. Asymptotically an @math{(r+1)}-way +algorithm is @m{O(N^{\log(2r+1)/\log(r+1)}), O(N^(log(2*r+1)/log(r+1)))}. Only +the pointwise multiplications count towards big-@math{O} complexity, but the +time spent in the evaluate and interpolate stages grows with @math{r} and has +a significant practical impact, with the asymptotic advantage of each @math{r} +realized only at bigger and bigger sizes. The overheads grow as +@m{O(Nr),O(N*r)}, whereas in an @math{r=2^k} FFT they grow only as @m{O(N \log +r), O(N*log(r))}. + +Knuth algorithm C evaluates at points 0,1,2,@dots{},@m{2r,2*r}, but exercise 4 +uses @math{-r},@dots{},0,@dots{},@math{r} and the latter saves some small +multiplies in the evaluate stage (or rather trades them for additions), and +has a further saving of nearly half the interpolate steps. The idea is to +separate odd and even final coefficients and then perform algorithm C steps C7 +and C8 on them separately. The divisors at step C7 become @math{j^2} and the +multipliers at C8 become @m{2tj-j^2,2*t*j-j^2}. + +Splitting odd and even parts through positive and negative points can be +thought of as using @math{-1} as a square root of unity. If a 4th root of +unity was available then a further split and speedup would be possible, but no +such root exists for plain integers. Going to complex integers with +@m{i=\sqrt{-1}, i=sqrt(-1)} doesn't help, essentially because in Cartesian +form it takes three real multiplies to do a complex multiply. The existence +of @m{2^k,2^k'}th roots of unity in a suitable ring or field lets the fast +Fourier transform keep splitting and get to @m{O(N \log r), O(N*log(r))}. + +Floating point FFTs use complex numbers approximating Nth roots of unity. +Some processors have special support for such FFTs. But these are not used in +GMP since it's very difficult to guarantee an exact result (to some number of +bits). An occasional difference of 1 in the last bit might not matter to a +typical signal processing algorithm, but is of course of vital importance to +GMP. + + +@node Unbalanced Multiplication, , Other Multiplication, Multiplication Algorithms +@subsection Unbalanced Multiplication +@cindex Unbalanced multiplication + +Multiplication of operands with different sizes, both below +@code{MUL_TOOM22_THRESHOLD} are done with plain schoolbook multiplication +(@pxref{Basecase Multiplication}). + +For really large operands, we invoke FFT directly. + +For operands between these sizes, we use Toom inspired algorithms suggested by +Alberto Zanoni and Marco Bodrato. The idea is to split the operands into +polynomials of different degree. GMP currently splits the smaller operand +into 2 coefficients, i.e., a polynomial of degree 1, but the larger operand +can be split into 2, 3, or 4 coefficients, i.e., a polynomial of degree 1 to +3. + +@c FIXME: This is mighty ugly, but a cleaner @need triggers texinfo bugs that +@c screws up layout here and there in the rest of the manual. +@c @tex +@c \goodbreak +@c @end tex +@node Division Algorithms, Greatest Common Divisor Algorithms, Multiplication Algorithms, Algorithms +@section Division Algorithms +@cindex Division algorithms + +@menu +* Single Limb Division:: +* Basecase Division:: +* Divide and Conquer Division:: +* Block-Wise Barrett Division:: +* Exact Division:: +* Exact Remainder:: +* Small Quotient Division:: +@end menu + + +@node Single Limb Division, Basecase Division, Division Algorithms, Division Algorithms +@subsection Single Limb Division + +N@cross{}1 division is implemented using repeated 2@cross{}1 divisions from +high to low, either with a hardware divide instruction or a multiplication by +inverse, whichever is best on a given CPU. + +The multiply by inverse follows ``Improved division by invariant integers'' by +M@"oller and Granlund (@pxref{References}) and is implemented as +@code{udiv_qrnnd_preinv} in @file{gmp-impl.h}. The idea is to have a +fixed-point approximation to @math{1/d} (see @code{invert_limb}) and then +multiply by the high limb (plus one bit) of the dividend to get a quotient +@math{q}. With @math{d} normalized (high bit set), @math{q} is no more than 1 +too small. Subtracting @m{qd,q*d} from the dividend gives a remainder, and +reveals whether @math{q} or @math{q-1} is correct. + +The result is a division done with two multiplications and four or five +arithmetic operations. On CPUs with low latency multipliers this can be much +faster than a hardware divide, though the cost of calculating the inverse at +the start may mean it's only better on inputs bigger than say 4 or 5 limbs. + +When a divisor must be normalized, either for the generic C +@code{__udiv_qrnnd_c} or the multiply by inverse, the division performed is +actually @m{a2^k,a*2^k} by @m{d2^k,d*2^k} where @math{a} is the dividend and +@math{k} is the power necessary to have the high bit of @m{d2^k,d*2^k} set. +The bit shifts for the dividend are usually accomplished ``on the fly'' +meaning by extracting the appropriate bits at each step. Done this way the +quotient limbs come out aligned ready to store. When only the remainder is +wanted, an alternative is to take the dividend limbs unshifted and calculate +@m{r = a \bmod d2^k, r = a mod d*2^k} followed by an extra final step @m{r2^k +\bmod d2^k, r*2^k mod d*2^k}. This can help on CPUs with poor bit shifts or +few registers. + +The multiply by inverse can be done two limbs at a time. The calculation is +basically the same, but the inverse is two limbs and the divisor treated as if +padded with a low zero limb. This means more work, since the inverse will +need a 2@cross{}2 multiply, but the four 1@cross{}1s to do that are +independent and can therefore be done partly or wholly in parallel. Likewise +for a 2@cross{}1 calculating @m{qd,q*d}. The net effect is to process two +limbs with roughly the same two multiplies worth of latency that one limb at a +time gives. This extends to 3 or 4 limbs at a time, though the extra work to +apply the inverse will almost certainly soon reach the limits of multiplier +throughput. + +A similar approach in reverse can be taken to process just half a limb at a +time if the divisor is only a half limb. In this case the 1@cross{}1 multiply +for the inverse effectively becomes two @m{{1\over2}\times1, (1/2)x1} for each +limb, which can be a saving on CPUs with a fast half limb multiply, or in fact +if the only multiply is a half limb, and especially if it's not pipelined. + + +@node Basecase Division, Divide and Conquer Division, Single Limb Division, Division Algorithms +@subsection Basecase Division + +Basecase N@cross{}M division is like long division done by hand, but in base +@m{2\GMPraise{@code{mp\_bits\_per\_limb}}, 2^mp_bits_per_limb}. See Knuth +section 4.3.1 algorithm D, and @file{mpn/generic/sb_divrem_mn.c}. + +Briefly stated, while the dividend remains larger than the divisor, a high +quotient limb is formed and the N@cross{}1 product @m{qd,q*d} subtracted at +the top end of the dividend. With a normalized divisor (most significant bit +set), each quotient limb can be formed with a 2@cross{}1 division and a +1@cross{}1 multiplication plus some subtractions. The 2@cross{}1 division is +by the high limb of the divisor and is done either with a hardware divide or a +multiply by inverse (the same as in @ref{Single Limb Division}) whichever is +faster. Such a quotient is sometimes one too big, requiring an addback of the +divisor, but that happens rarely. + +With Q=N@minus{}M being the number of quotient limbs, this is an +@m{O(QM),O(Q*M)} algorithm and will run at a speed similar to a basecase +Q@cross{}M multiplication, differing in fact only in the extra multiply and +divide for each of the Q quotient limbs. + + +@node Divide and Conquer Division, Block-Wise Barrett Division, Basecase Division, Division Algorithms +@subsection Divide and Conquer Division + +For divisors larger than @code{DC_DIV_QR_THRESHOLD}, division is done by dividing. +Or to be precise by a recursive divide and conquer algorithm based on work by +Moenck and Borodin, Jebelean, and Burnikel and Ziegler (@pxref{References}). + +The algorithm consists essentially of recognising that a 2N@cross{}N division +can be done with the basecase division algorithm (@pxref{Basecase Division}), +but using N/2 limbs as a base, not just a single limb. This way the +multiplications that arise are (N/2)@cross{}(N/2) and can take advantage of +Karatsuba and higher multiplication algorithms (@pxref{Multiplication +Algorithms}). The two ``digits'' of the quotient are formed by recursive +N@cross{}(N/2) divisions. + +If the (N/2)@cross{}(N/2) multiplies are done with a basecase multiplication +then the work is about the same as a basecase division, but with more function +call overheads and with some subtractions separated from the multiplies. +These overheads mean that it's only when N/2 is above +@code{MUL_TOOM22_THRESHOLD} that divide and conquer is of use. + +@code{DC_DIV_QR_THRESHOLD} is based on the divisor size N, so it will be somewhere +above twice @code{MUL_TOOM22_THRESHOLD}, but how much above depends on the +CPU@. An optimized @code{mpn_mul_basecase} can lower @code{DC_DIV_QR_THRESHOLD} a +little by offering a ready-made advantage over repeated @code{mpn_submul_1} +calls. + +Divide and conquer is asymptotically @m{O(M(N)\log N),O(M(N)*log(N))} where +@math{M(N)} is the time for an N@cross{}N multiplication done with FFTs. The +actual time is a sum over multiplications of the recursed sizes, as can be +seen near the end of section 2.2 of Burnikel and Ziegler. For example, within +the Toom-3 range, divide and conquer is @m{2.63M(N), 2.63*M(N)}. With higher +algorithms the @math{M(N)} term improves and the multiplier tends to @m{\log +N, log(N)}. In practice, at moderate to large sizes, a 2N@cross{}N division +is about 2 to 4 times slower than an N@cross{}N multiplication. + + +@node Block-Wise Barrett Division, Exact Division, Divide and Conquer Division, Division Algorithms +@subsection Block-Wise Barrett Division + +For the largest divisions, a block-wise Barrett division algorithm is used. +Here, the divisor is inverted to a precision determined by the relative size of +the dividend and divisor. Blocks of quotient limbs are then generated by +multiplying blocks from the dividend by the inverse. + +Our block-wise algorithm computes a smaller inverse than in the plain Barrett +algorithm. For a @math{2n/n} division, the inverse will be just @m{\lceil n/2 +\rceil, ceil(n/2)} limbs. + + +@node Exact Division, Exact Remainder, Block-Wise Barrett Division, Division Algorithms +@subsection Exact Division + + +A so-called exact division is when the dividend is known to be an exact +multiple of the divisor. Jebelean's exact division algorithm uses this +knowledge to make some significant optimizations (@pxref{References}). + +The idea can be illustrated in decimal for example with 368154 divided by +543. Because the low digit of the dividend is 4, the low digit of the +quotient must be 8. This is arrived at from @m{4 \mathord{\times} 7 \bmod 10, +4*7 mod 10}, using the fact 7 is the modular inverse of 3 (the low digit of +the divisor), since @m{3 \mathord{\times} 7 \mathop{\equiv} 1 \bmod 10, 3*7 +@equiv{} 1 mod 10}. So @m{8\mathord{\times}543 = 4344,8*543=4344} can be +subtracted from the dividend leaving 363810. Notice the low digit has become +zero. + +The procedure is repeated at the second digit, with the next quotient digit 7 +(@m{1 \mathord{\times} 7 \bmod 10, 7 @equiv{} 1*7 mod 10}), subtracting +@m{7\mathord{\times}543 = 3801,7*543=3801}, leaving 325800. And finally at +the third digit with quotient digit 6 (@m{8 \mathord{\times} 7 \bmod 10, 8*7 +mod 10}), subtracting @m{6\mathord{\times}543 = 3258,6*543=3258} leaving 0. +So the quotient is 678. + +Notice however that the multiplies and subtractions don't need to extend past +the low three digits of the dividend, since that's enough to determine the +three quotient digits. For the last quotient digit no subtraction is needed +at all. On a 2N@cross{}N division like this one, only about half the work of +a normal basecase division is necessary. + +For an N@cross{}M exact division producing Q=N@minus{}M quotient limbs, the +saving over a normal basecase division is in two parts. Firstly, each of the +Q quotient limbs needs only one multiply, not a 2@cross{}1 divide and +multiply. Secondly, the crossproducts are reduced when @math{Q>M} to +@m{QM-M(M+1)/2,Q*M-M*(M+1)/2}, or when @math{Q@le{}M} to @m{Q(Q-1)/2, +Q*(Q-1)/2}. Notice the savings are complementary. If Q is big then many +divisions are saved, or if Q is small then the crossproducts reduce to a small +number. + +The modular inverse used is calculated efficiently by @code{binvert_limb} in +@file{gmp-impl.h}. This does four multiplies for a 32-bit limb, or six for a +64-bit limb. @file{tune/modlinv.c} has some alternate implementations that +might suit processors better at bit twiddling than multiplying. + +The sub-quadratic exact division described by Jebelean in ``Exact Division +with Karatsuba Complexity'' is not currently implemented. It uses a +rearrangement similar to the divide and conquer for normal division +(@pxref{Divide and Conquer Division}), but operating from low to high. A +further possibility not currently implemented is ``Bidirectional Exact Integer +Division'' by Krandick and Jebelean which forms quotient limbs from both the +high and low ends of the dividend, and can halve once more the number of +crossproducts needed in a 2N@cross{}N division. + +A special case exact division by 3 exists in @code{mpn_divexact_by3}, +supporting Toom-3 multiplication and @code{mpq} canonicalizations. It forms +quotient digits with a multiply by the modular inverse of 3 (which is +@code{0xAA..AAB}) and uses two comparisons to determine a borrow for the next +limb. The multiplications don't need to be on the dependent chain, as long as +the effect of the borrows is applied, which can help chips with pipelined +multipliers. + + +@node Exact Remainder, Small Quotient Division, Exact Division, Division Algorithms +@subsection Exact Remainder +@cindex Exact remainder + +If the exact division algorithm is done with a full subtraction at each stage +and the dividend isn't a multiple of the divisor, then low zero limbs are +produced but with a remainder in the high limbs. For dividend @math{a}, +divisor @math{d}, quotient @math{q}, and @m{b = 2 +\GMPraise{@code{mp\_bits\_per\_limb}}, b = 2^mp_bits_per_limb}, this remainder +@math{r} is of the form +@tex +$$ a = qd + r b^n $$ +@end tex +@ifnottex + +@example +a = q*d + r*b^n +@end example + +@end ifnottex +@math{n} represents the number of zero limbs produced by the subtractions, +that being the number of limbs produced for @math{q}. @math{r} will be in the +range @math{0@le{}r b \GMPhat r ++ u_2, v2*q>b*r+u2} condition appropriately relaxed. + + +@need 1000 +@node Greatest Common Divisor Algorithms, Powering Algorithms, Division Algorithms, Algorithms +@section Greatest Common Divisor +@cindex Greatest common divisor algorithms +@cindex GCD algorithms + +@menu +* Binary GCD:: +* Lehmer's Algorithm:: +* Subquadratic GCD:: +* Extended GCD:: +* Jacobi Symbol:: +@end menu + + +@node Binary GCD, Lehmer's Algorithm, Greatest Common Divisor Algorithms, Greatest Common Divisor Algorithms +@subsection Binary GCD + +At small sizes GMP uses an @math{O(N^2)} binary style GCD@. This is described +in many textbooks, for example Knuth section 4.5.2 algorithm B@. It simply +consists of successively reducing odd operands @math{a} and @math{b} using + +@quotation +@math{a,b = @abs{}(a-b),@min{}(a,b)} @* +strip factors of 2 from @math{a} +@end quotation + +The Euclidean GCD algorithm, as per Knuth algorithms E and A, repeatedly +computes the quotient @m{q = \lfloor a/b \rfloor, q = floor(a/b)} and replaces +@math{a,b} by @math{v, u - q v}. The binary algorithm has so far been found to +be faster than the Euclidean algorithm everywhere. One reason the binary +method does well is that the implied quotient at each step is usually small, +so often only one or two subtractions are needed to get the same effect as a +division. Quotients 1, 2 and 3 for example occur 67.7% of the time, see Knuth +section 4.5.3 Theorem E. + +When the implied quotient is large, meaning @math{b} is much smaller than +@math{a}, then a division is worthwhile. This is the basis for the initial +@math{a @bmod b} reductions in @code{mpn_gcd} and @code{mpn_gcd_1} (the latter +for both N@cross{}1 and 1@cross{}1 cases). But after that initial reduction, +big quotients occur too rarely to make it worth checking for them. + +@sp 1 +The final @math{1@cross{}1} GCD in @code{mpn_gcd_1} is done in the generic C +code as described above. For two N-bit operands, the algorithm takes about +0.68 iterations per bit. For optimum performance some attention needs to be +paid to the way the factors of 2 are stripped from @math{a}. + +Firstly it may be noted that in two's complement the number of low zero bits on +@math{a-b} is the same as @math{b-a}, so counting or testing can begin on +@math{a-b} without waiting for @math{@abs{}(a-b)} to be determined. + +A loop stripping low zero bits tends not to branch predict well, since the +condition is data dependent. But on average there's only a few low zeros, so +an option is to strip one or two bits arithmetically then loop for more (as +done for AMD K6). Or use a lookup table to get a count for several bits then +loop for more (as done for AMD K7). An alternative approach is to keep just +one of @math{a} and @math{b} odd and iterate + +@quotation +@math{a,b = @abs{}(a-b), @min{}(a,b)} @* +@math{a = a/2} if even @* +@math{b = b/2} if even +@end quotation + +This requires about 1.25 iterations per bit, but stripping of a single bit at +each step avoids any branching. Repeating the bit strip reduces to about 0.9 +iterations per bit, which may be a worthwhile tradeoff. + +Generally with the above approaches a speed of perhaps 6 cycles per bit can be +achieved, which is still not terribly fast with for instance a 64-bit GCD +taking nearly 400 cycles. It's this sort of time which means it's not usually +advantageous to combine a set of divisibility tests into a GCD. + +Currently, the binary algorithm is used for GCD only when @math{N < 3}. + +@node Lehmer's Algorithm, Subquadratic GCD, Binary GCD, Greatest Common Divisor Algorithms +@comment node-name, next, previous, up +@subsection Lehmer's algorithm + +Lehmer's improvement of the Euclidean algorithms is based on the observation +that the initial part of the quotient sequence depends only on the most +significant parts of the inputs. The variant of Lehmer's algorithm used in GMP +splits off the most significant two limbs, as suggested, e.g., in ``A +Double-Digit Lehmer-Euclid Algorithm'' by Jebelean (@pxref{References}). The +quotients of two double-limb inputs are collected as a 2 by 2 matrix with +single-limb elements. This is done by the function @code{mpn_hgcd2}. The +resulting matrix is applied to the inputs using @code{mpn_mul_1} and +@code{mpn_submul_1}. Each iteration usually reduces the inputs by almost one +limb. In the rare case of a large quotient, no progress can be made by +examining just the most significant two limbs, and the quotient is computed +using plain division. + +The resulting algorithm is asymptotically @math{O(N^2)}, just as the Euclidean +algorithm and the binary algorithm. The quadratic part of the work are +the calls to @code{mpn_mul_1} and @code{mpn_submul_1}. For small sizes, the +linear work is also significant. There are roughly @math{N} calls to the +@code{mpn_hgcd2} function. This function uses a couple of important +optimizations: + +@itemize +@item +It uses the same relaxed notion of correctness as @code{mpn_hgcd} (see next +section). This means that when called with the most significant two limbs of +two large numbers, the returned matrix does not always correspond exactly to +the initial quotient sequence for the two large numbers; the final quotient +may sometimes be one off. + +@item +It takes advantage of the fact that the quotients are usually small. The division +operator is not used, since the corresponding assembler instruction is very +slow on most architectures. (This code could probably be improved further, it +uses many branches that are unfriendly to prediction.) + +@item +It switches from double-limb calculations to single-limb calculations half-way +through, when the input numbers have been reduced in size from two limbs to +one and a half. + +@end itemize + +@node Subquadratic GCD, Extended GCD, Lehmer's Algorithm, Greatest Common Divisor Algorithms +@subsection Subquadratic GCD + +For inputs larger than @code{GCD_DC_THRESHOLD}, GCD is computed via the HGCD +(Half GCD) function, as a generalization to Lehmer's algorithm. + +Let the inputs @math{a,b} be of size @math{N} limbs each. Put @m{S=\lfloor N/2 +\rfloor + 1, S = floor(N/2) + 1}. Then HGCD(a,b) returns a transformation +matrix @math{T} with non-negative elements, and reduced numbers @math{(c;d) = +T^{-1} (a;b)}. The reduced numbers @math{c,d} must be larger than @math{S} +limbs, while their difference @math{abs(c-d)} must fit in @math{S} limbs. The +matrix elements will also be of size roughly @math{N/2}. + +The HGCD base case uses Lehmer's algorithm, but with the above stop condition +that returns reduced numbers and the corresponding transformation matrix +half-way through. For inputs larger than @code{HGCD_THRESHOLD}, HGCD is +computed recursively, using the divide and conquer algorithm in ``On +Sch@"onhage's algorithm and subquadratic integer GCD computation'' by M@"oller +(@pxref{References}). The recursive algorithm consists of these main +steps. + +@itemize + +@item +Call HGCD recursively, on the most significant @math{N/2} limbs. Apply the +resulting matrix @math{T_1} to the full numbers, reducing them to a size just +above @math{3N/2}. + +@item +Perform a small number of division or subtraction steps to reduce the numbers +to size below @math{3N/2}. This is essential mainly for the unlikely case of +large quotients. + +@item +Call HGCD recursively, on the most significant @math{N/2} limbs of the reduced +numbers. Apply the resulting matrix @math{T_2} to the full numbers, reducing +them to a size just above @math{N/2}. + +@item +Compute @math{T = T_1 T_2}. + +@item +Perform a small number of division and subtraction steps to satisfy the +requirements, and return. +@end itemize + +GCD is then implemented as a loop around HGCD, similarly to Lehmer's +algorithm. Where Lehmer repeatedly chops off the top two limbs, calls +@code{mpn_hgcd2}, and applies the resulting matrix to the full numbers, the +sub-quadratic GCD chops off the most significant third of the limbs (the +proportion is a tuning parameter, and @math{1/3} seems to be more efficient +than, e.g., @math{1/2}), calls @code{mpn_hgcd}, and applies the resulting +matrix. Once the input numbers are reduced to size below +@code{GCD_DC_THRESHOLD}, Lehmer's algorithm is used for the rest of the work. + +The asymptotic running time of both HGCD and GCD is @m{O(M(N)\log N),O(M(N)*log(N))}, +where @math{M(N)} is the time for multiplying two @math{N}-limb numbers. + +@comment node-name, next, previous, up + +@node Extended GCD, Jacobi Symbol, Subquadratic GCD, Greatest Common Divisor Algorithms +@subsection Extended GCD + +The extended GCD function, or GCDEXT, calculates @math{@gcd{}(a,b)} and also +cofactors @math{x} and @math{y} satisfying @m{ax+by=\gcd(a@C{}b), +a*x+b*y=gcd(a@C{}b)}. All the algorithms used for plain GCD are extended to +handle this case. The binary algorithm is used only for single-limb GCDEXT. +Lehmer's algorithm is used for sizes up to @code{GCDEXT_DC_THRESHOLD}. Above +this threshold, GCDEXT is implemented as a loop around HGCD, but with more +book-keeping to keep track of the cofactors. This gives the same asymptotic +running time as for GCD and HGCD, @m{O(M(N)\log N),O(M(N)*log(N))}. + +One difference to plain GCD is that while the inputs @math{a} and @math{b} are +reduced as the algorithm proceeds, the cofactors @math{x} and @math{y} grow in +size. This makes the tuning of the chopping-point more difficult. The current +code chops off the most significant half of the inputs for the call to HGCD in +the first iteration, and the most significant two thirds for the remaining +calls. This strategy could surely be improved. Also the stop condition for the +loop, where Lehmer's algorithm is invoked once the inputs are reduced below +@code{GCDEXT_DC_THRESHOLD}, could maybe be improved by taking into account the +current size of the cofactors. + +@node Jacobi Symbol, , Extended GCD, Greatest Common Divisor Algorithms +@subsection Jacobi Symbol +@cindex Jacobi symbol algorithm + +@c Editor Note: I don't see other people defining the inputs, it would be nice +@c here because the code uses (a/b) where other references use (n/k) + +Jacobi symbol @m{\left(a \over b\right), (@var{a}/@var{b})} + +Initially if either operand fits in a single limb, a reduction is done with +either @code{mpn_mod_1} or @code{mpn_modexact_1_odd}, followed by the binary +algorithm on a single limb. The binary algorithm is well suited to a single limb, +and the whole calculation in this case is quite efficient. + +For inputs larger than @code{GCD_DC_THRESHOLD}, @code{mpz_jacobi}, +@code{mpz_legendre} and @code{mpz_kronecker} are computed via the HGCD (Half +GCD) function, as a generalization to Lehmer's algorithm. + +Most GCD algorithms reduce @math{a} and @math{b} by repeatedly computing the +quotient @m{q = \lfloor a/b \rfloor, q = floor(a/b)} and iteratively replacing + +@c Couldn't figure out macros with commas. +@tex +$$ a, b = b, a - q * b$$ +@end tex +@ifnottex +@math{a, b = b, a - q * b} +@end ifnottex + +Different algorithms use different methods for calculating q, but the core +algorithm is the same if we use @ref{Lehmer's Algorithm} or +@ref{Subquadratic GCD, HGCD}. + +At each step it is possible to compute if the reduction inverts the Jacobi +symbol based on the two least significant bits of @var{a} and @var{b}. For +more details see ``Efficient computation of the Jacobi symbol'' by +M@"oller (@pxref{References}). + +A small set of bits is thus used to track state +@itemize +@item +current sign of result (1 bit) + +@item +two least significant bits of @var{a} and @var{b} (4 bits) + +@item +a pointer to which input is currently the denominator (1 bit) +@end itemize + +In all the routines sign changes for the result are accumulated using fast bit +twiddling which avoids conditional jumps. + +The final result is calculated after verifying the inputs are coprime (GCD = 1) +by raising @m{(-1)^e,(-1)^e}. + +Much of the HGCD code is shared directly with the HGCD implementations, such +as the 2x2 matrix calculation, @xref{Lehmer's Algorithm} basecase and +@code{GCD_DC_THRESHOLD}. + +The asymptotic running time is @m{O(M(N)\log N),O(M(N)*log(N))}, where +@math{M(N)} is the time for multiplying two @math{N}-limb numbers. + +@need 1000 +@node Powering Algorithms, Root Extraction Algorithms, Greatest Common Divisor Algorithms, Algorithms +@section Powering Algorithms +@cindex Powering algorithms + +@menu +* Normal Powering Algorithm:: +* Modular Powering Algorithm:: +@end menu + + +@node Normal Powering Algorithm, Modular Powering Algorithm, Powering Algorithms, Powering Algorithms +@subsection Normal Powering + +Normal @code{mpz} or @code{mpf} powering uses a simple binary algorithm, +successively squaring and then multiplying by the base when a 1 bit is seen in +the exponent, as per Knuth section 4.6.3. The ``left to right'' +variant described there is used rather than algorithm A, since it's just as +easy and can be done with somewhat less temporary memory. + + +@node Modular Powering Algorithm, , Normal Powering Algorithm, Powering Algorithms +@subsection Modular Powering + +Modular powering is implemented using a @math{2^k}-ary sliding window +algorithm, as per ``Handbook of Applied Cryptography'' algorithm 14.85 +(@pxref{References}). @math{k} is chosen according to the size of the +exponent. Larger exponents use larger values of @math{k}, the choice being +made to minimize the average number of multiplications that must supplement +the squaring. + +The modular multiplies and squarings use either a simple division or the REDC +method by Montgomery (@pxref{References}). REDC is a little faster, +essentially saving N single limb divisions in a fashion similar to an exact +remainder (@pxref{Exact Remainder}). + + +@node Root Extraction Algorithms, Radix Conversion Algorithms, Powering Algorithms, Algorithms +@section Root Extraction Algorithms +@cindex Root extraction algorithms + +@menu +* Square Root Algorithm:: +* Nth Root Algorithm:: +* Perfect Square Algorithm:: +* Perfect Power Algorithm:: +@end menu + + +@node Square Root Algorithm, Nth Root Algorithm, Root Extraction Algorithms, Root Extraction Algorithms +@subsection Square Root +@cindex Square root algorithm +@cindex Karatsuba square root algorithm + +Square roots are taken using the ``Karatsuba Square Root'' algorithm by Paul +Zimmermann (@pxref{References}). + +An input @math{n} is split into four parts of @math{k} bits each, so with +@math{b=2^k} we have @m{n = a_3b^3 + a_2b^2 + a_1b + a_0, n = a3*b^3 + a2*b^2 ++ a1*b + a0}. Part @ms{a,3} must be ``normalized'' so that either the high or +second highest bit is set. In GMP, @math{k} is kept on a limb boundary and +the input is left shifted (by an even number of bits) to normalize. + +The square root of the high two parts is taken, by recursive application of +the algorithm (bottoming out in a one-limb Newton's method), +@tex +$$ s',r' = \mathop{\rm sqrtrem} \> (a_3b + a_2) $$ +@end tex +@ifnottex + +@example +s1,r1 = sqrtrem (a3*b + a2) +@end example + +@end ifnottex +This is an approximation to the desired root and is extended by a division to +give @math{s},@math{r}, +@tex +$$\eqalign{ +q,u &= \mathop{\rm divrem} \> (r'b + a_1, 2s') \cr +s &= s'b + q \cr +r &= ub + a_0 - q^2 +}$$ +@end tex +@ifnottex + +@example +q,u = divrem (r1*b + a1, 2*s1) +s = s1*b + q +r = u*b + a0 - q^2 +@end example + +@end ifnottex +The normalization requirement on @ms{a,3} means at this point @math{s} is +either correct or 1 too big. @math{r} is negative in the latter case, so +@tex +$$\eqalign{ +\mathop{\rm if} \; r &< 0 \; \mathop{\rm then} \cr +r &\leftarrow r + 2s - 1 \cr +s &\leftarrow s - 1 +}$$ +@end tex +@ifnottex + +@example +if r < 0 then + r = r + 2*s - 1 + s = s - 1 +@end example + +@end ifnottex +The algorithm is expressed in a divide and conquer form, but as noted in the +paper it can also be viewed as a discrete variant of Newton's method, or as a +variation on the schoolboy method (no longer taught) for square roots two +digits at a time. + +If the remainder @math{r} is not required then usually only a few high limbs +of @math{r} and @math{u} need to be calculated to determine whether an +adjustment to @math{s} is required. This optimization is not currently +implemented. + +In the Karatsuba multiplication range this algorithm is @m{O({3\over2} +M(N/2)),O(1.5*M(N/2))}, where @math{M(n)} is the time to multiply two numbers +of @math{n} limbs. In the FFT multiplication range this grows to a bound of +@m{O(6 M(N/2)),O(6*M(N/2))}. In practice a factor of about 1.5 to 1.8 is +found in the Karatsuba and Toom-3 ranges, growing to 2 or 3 in the FFT range. + +The algorithm does all its calculations in integers and the resulting +@code{mpn_sqrtrem} is used for both @code{mpz_sqrt} and @code{mpf_sqrt}. +The extended precision given by @code{mpf_sqrt_ui} is obtained by +padding with zero limbs. + + +@node Nth Root Algorithm, Perfect Square Algorithm, Square Root Algorithm, Root Extraction Algorithms +@subsection Nth Root +@cindex Root extraction algorithm +@cindex Nth root algorithm + +Integer Nth roots are taken using Newton's method with the following +iteration, where @math{A} is the input and @math{n} is the root to be taken. +@tex +$$a_{i+1} = {1\over n} \left({A \over a_i^{n-1}} + (n-1)a_i \right)$$ +@end tex +@ifnottex + +@example + 1 A +a[i+1] = - * ( --------- + (n-1)*a[i] ) + n a[i]^(n-1) +@end example + +@end ifnottex +The initial approximation @m{a_1,a[1]} is generated bitwise by successively +powering a trial root with or without new 1 bits, aiming to be just above the +true root. The iteration converges quadratically when started from a good +approximation. When @math{n} is large more initial bits are needed to get +good convergence. The current implementation is not particularly well +optimized. + + +@node Perfect Square Algorithm, Perfect Power Algorithm, Nth Root Algorithm, Root Extraction Algorithms +@subsection Perfect Square +@cindex Perfect square algorithm + +A significant fraction of non-squares can be quickly identified by checking +whether the input is a quadratic residue modulo small integers. + +@code{mpz_perfect_square_p} first tests the input mod 256, which means just +examining the low byte. Only 44 different values occur for squares mod 256, +so 82.8% of inputs can be immediately identified as non-squares. + +On a 32-bit system similar tests are done mod 9, 5, 7, 13 and 17, for a total +99.25% of inputs identified as non-squares. On a 64-bit system 97 is tested +too, for a total 99.62%. + +These moduli are chosen because they're factors of @math{2^@W{24}-1} (or +@math{2^@W{48}-1} for 64-bits), and such a remainder can be quickly taken just +using additions (see @code{mpn_mod_34lsub1}). + +When nails are in use moduli are instead selected by the @file{gen-psqr.c} +program and applied with an @code{mpn_mod_1}. The same @math{2^@W{24}-1} or +@math{2^@W{48}-1} could be done with nails using some extra bit shifts, but +this is not currently implemented. + +In any case each modulus is applied to the @code{mpn_mod_34lsub1} or +@code{mpn_mod_1} remainder and a table lookup identifies non-squares. By +using a ``modexact'' style calculation, and suitably permuted tables, just one +multiply each is required, see the code for details. Moduli are also combined +to save operations, so long as the lookup tables don't become too big. +@file{gen-psqr.c} does all the pre-calculations. + +A square root must still be taken for any value that passes these tests, to +verify it's really a square and not one of the small fraction of non-squares +that get through (i.e.@: a pseudo-square to all the tested bases). + +Clearly more residue tests could be done, @code{mpz_perfect_square_p} only +uses a compact and efficient set. Big inputs would probably benefit from more +residue testing, small inputs might be better off with less. The assumed +distribution of squares versus non-squares in the input would affect such +considerations. + + +@node Perfect Power Algorithm, , Perfect Square Algorithm, Root Extraction Algorithms +@subsection Perfect Power +@cindex Perfect power algorithm + +Detecting perfect powers is required by some factorization algorithms. +Currently @code{mpz_perfect_power_p} is implemented using repeated Nth root +extractions, though naturally only prime roots need to be considered. +(@xref{Nth Root Algorithm}.) + +If a prime divisor @math{p} with multiplicity @math{e} can be found, then only +roots which are divisors of @math{e} need to be considered, much reducing the +work necessary. To this end divisibility by a set of small primes is checked. + + +@node Radix Conversion Algorithms, Other Algorithms, Root Extraction Algorithms, Algorithms +@section Radix Conversion +@cindex Radix conversion algorithms + +Radix conversions are less important than other algorithms. A program +dominated by conversions should probably use a different data representation. + +@menu +* Binary to Radix:: +* Radix to Binary:: +@end menu + + +@node Binary to Radix, Radix to Binary, Radix Conversion Algorithms, Radix Conversion Algorithms +@subsection Binary to Radix + +Conversions from binary to a power-of-2 radix use a simple and fast +@math{O(N)} bit extraction algorithm. + +Conversions from binary to other radices use one of two algorithms. Sizes +below @code{GET_STR_PRECOMPUTE_THRESHOLD} use a basic @math{O(N^2)} method. +Repeated divisions by @math{b^n} are made, where @math{b} is the radix and +@math{n} is the biggest power that fits in a limb. But instead of simply +using the remainder @math{r} from such divisions, an extra divide step is done +to give a fractional limb representing @math{r/b^n}. The digits of @math{r} +can then be extracted using multiplications by @math{b} rather than divisions. +Special case code is provided for decimal, allowing multiplications by 10 to +optimize to shifts and adds. + +Above @code{GET_STR_PRECOMPUTE_THRESHOLD} a sub-quadratic algorithm is used. +For an input @math{t}, powers @m{b^{n2^i},b^(n*2^i)} of the radix are +calculated, until a power between @math{t} and @m{\sqrt{t},sqrt(t)} is +reached. @math{t} is then divided by that largest power, giving a quotient +which is the digits above that power, and a remainder which is those below. +These two parts are in turn divided by the second highest power, and so on +recursively. When a piece has been divided down to less than +@code{GET_STR_DC_THRESHOLD} limbs, the basecase algorithm described above is +used. + +The advantage of this algorithm is that big divisions can make use of the +sub-quadratic divide and conquer division (@pxref{Divide and Conquer +Division}), and big divisions tend to have less overheads than lots of +separate single limb divisions anyway. But in any case the cost of +calculating the powers @m{b^{n2^i},b^(n*2^i)} must first be overcome. + +@code{GET_STR_PRECOMPUTE_THRESHOLD} and @code{GET_STR_DC_THRESHOLD} represent +the same basic thing, the point where it becomes worth doing a big division to +cut the input in half. @code{GET_STR_PRECOMPUTE_THRESHOLD} includes the cost +of calculating the radix power required, whereas @code{GET_STR_DC_THRESHOLD} +assumes that's already available, which is the case when recursing. + +Since the base case produces digits from least to most significant but they +want to be stored from most to least, it's necessary to calculate in advance +how many digits there will be, or at least be sure not to underestimate that. +For GMP the number of input bits is multiplied by @code{chars_per_bit_exactly} +from @code{mp_bases}, rounding up. The result is either correct or one too +big. + +Examining some of the high bits of the input could increase the chance of +getting the exact number of digits, but an exact result every time would not +be practical, since in general the difference between numbers 100@dots{} and +99@dots{} is only in the last few bits and the work to identify 99@dots{} +might well be almost as much as a full conversion. + +The @math{r/b^n} scheme described above for using multiplications to bring out +digits might be useful for more than a single limb. Some brief experiments +with it on the base case when recursing didn't give a noticeable improvement, +but perhaps that was only due to the implementation. Something similar would +work for the sub-quadratic divisions too, though there would be the cost of +calculating a bigger radix power. + +Another possible improvement for the sub-quadratic part would be to arrange +for radix powers that balanced the sizes of quotient and remainder produced, +i.e.@: the highest power would be an @m{b^{nk},b^(n*k)} approximately equal to +@m{\sqrt{t},sqrt(t)}, not restricted to a @math{2^i} factor. That ought to +smooth out a graph of times against sizes, but may or may not be a net +speedup. + + +@node Radix to Binary, , Binary to Radix, Radix Conversion Algorithms +@subsection Radix to Binary + +@strong{This section needs to be rewritten, it currently describes the +algorithms used before GMP 4.3.} + +Conversions from a power-of-2 radix into binary use a simple and fast +@math{O(N)} bitwise concatenation algorithm. + +Conversions from other radices use one of two algorithms. Sizes below +@code{SET_STR_PRECOMPUTE_THRESHOLD} use a basic @math{O(N^2)} method. Groups +of @math{n} digits are converted to limbs, where @math{n} is the biggest +power of the base @math{b} which will fit in a limb, then those groups are +accumulated into the result by multiplying by @math{b^n} and adding. This +saves multi-precision operations, as per Knuth section 4.4 part E +(@pxref{References}). Some special case code is provided for decimal, giving +the compiler a chance to optimize multiplications by 10. + +Above @code{SET_STR_PRECOMPUTE_THRESHOLD} a sub-quadratic algorithm is used. +First groups of @math{n} digits are converted into limbs. Then adjacent +limbs are combined into limb pairs with @m{xb^n+y,x*b^n+y}, where @math{x} +and @math{y} are the limbs. Adjacent limb pairs are combined into quads +similarly with @m{xb^{2n}+y,x*b^(2n)+y}. This continues until a single block +remains, that being the result. + +The advantage of this method is that the multiplications for each @math{x} are +big blocks, allowing Karatsuba and higher algorithms to be used. But the cost +of calculating the powers @m{b^{n2^i},b^(n*2^i)} must be overcome. +@code{SET_STR_PRECOMPUTE_THRESHOLD} usually ends up quite big, around 5000 digits, and on +some processors much bigger still. + +@code{SET_STR_PRECOMPUTE_THRESHOLD} is based on the input digits (and tuned +for decimal), though it might be better based on a limb count, so as to be +independent of the base. But that sort of count isn't used by the base case +and so would need some sort of initial calculation or estimate. + +The main reason @code{SET_STR_PRECOMPUTE_THRESHOLD} is so much bigger than the +corresponding @code{GET_STR_PRECOMPUTE_THRESHOLD} is that @code{mpn_mul_1} is +much faster than @code{mpn_divrem_1} (often by a factor of 5, or more). + + +@need 1000 +@node Other Algorithms, Assembly Coding, Radix Conversion Algorithms, Algorithms +@section Other Algorithms + +@menu +* Prime Testing Algorithm:: +* Factorial Algorithm:: +* Binomial Coefficients Algorithm:: +* Fibonacci Numbers Algorithm:: +* Lucas Numbers Algorithm:: +* Random Number Algorithms:: +@end menu + + +@node Prime Testing Algorithm, Factorial Algorithm, Other Algorithms, Other Algorithms +@subsection Prime Testing +@cindex Prime testing algorithms + +The primality testing in @code{mpz_probab_prime_p} (@pxref{Number Theoretic +Functions}) first does some trial division by small factors and then uses the +Miller-Rabin probabilistic primality testing algorithm, as described in Knuth +section 4.5.4 algorithm P (@pxref{References}). + +For an odd input @math{n}, and with @math{n = q@GMPmultiply{}2^k+1} where +@math{q} is odd, this algorithm selects a random base @math{x} and tests +whether @math{x^q @bmod{} n} is 1 or @math{-1}, or an @m{x^{q2^j} \bmod n, +x^(q*2^j) mod n} is @math{1}, for @math{1@le{}j@le{}k}. If so then @math{n} +is probably prime, if not then @math{n} is definitely composite. + +Any prime @math{n} will pass the test, but some composites do too. Such +composites are known as strong pseudoprimes to base @math{x}. No @math{n} is +a strong pseudoprime to more than @math{1/4} of all bases (see Knuth exercise +22), hence with @math{x} chosen at random there's no more than a @math{1/4} +chance a ``probable prime'' will in fact be composite. + +In fact strong pseudoprimes are quite rare, making the test much more +powerful than this analysis would suggest, but @math{1/4} is all that's proven +for an arbitrary @math{n}. + + +@node Factorial Algorithm, Binomial Coefficients Algorithm, Prime Testing Algorithm, Other Algorithms +@subsection Factorial +@cindex Factorial algorithm + +Factorials are calculated by a combination of two algorithms. An idea is +shared among them: to compute the odd part of the factorial; a final step +takes account of the power of @math{2} term, by shifting. + +For small @math{n}, the odd factor of @math{n!} is computed with the simple +observation that it is equal to the product of all positive odd numbers +smaller than @math{n} times the odd factor of @m{\lfloor n/2\rfloor!, [n/2]!}, +where @m{\lfloor x\rfloor, [x]} is the integer part of @math{x}, and so on +recursively. The procedure can be best illustrated with an example, + +@quotation +@math{23! = (23.21.19.17.15.13.11.9.7.5.3)(11.9.7.5.3)(5.3)2^{19}} +@end quotation + +Current code collects all the factors in a single list, with a loop and no +recursion, and computes the product, with no special care for repeated chunks. + +When @math{n} is larger, computations pass through prime sieving. A helper +function is used, as suggested by Peter Luschny: +@tex +$$\mathop{\rm msf}(n) = {n!\over\lfloor n/2\rfloor!^2\cdot2^k} = \prod_{p=3}^{n} +p^{\mathop{\rm L}(p,n)} $$ +@end tex +@ifnottex + +@example + n + ----- + n! | | L(p,n) +msf(n) = -------------- = | | p + [n/2]!^2.2^k p=3 +@end example +@end ifnottex + +Where @math{p} ranges on odd prime numbers. The exponent @math{k} is chosen to +obtain an odd integer number: @math{k} is the number of 1 bits in the binary +representation of @m{\lfloor n/2\rfloor, [n/2]}. The function L@math{(p,n)} +can be defined as zero when @math{p} is composite, and, for any prime +@math{p}, it is computed with: +@tex +$$\mathop{\rm L}(p,n) = \sum_{i>0}\left\lfloor{n\over p^i}\right\rfloor\bmod2 +\leq\log_p(n)$$ +@end tex +@ifnottex + +@example + --- + \ n +L(p,n) = / [---] mod 2 <= log (n) . + --- p^i p + i>0 +@end example +@end ifnottex + +With this helper function, we are able to compute the odd part of @math{n!} +using the recursion implied by @m{n!=\lfloor n/2\rfloor!^2\cdot\mathop{\rm +msf}(n)\cdot2^k , n!=[n/2]!^2*msf(n)*2^k}. The recursion stops using the +small-@math{n} algorithm on some @m{\lfloor n/2^i\rfloor, [n/2^i]}. + +Both the above algorithms use binary splitting to compute the product of many +small factors. At first as many products as possible are accumulated in a +single register, generating a list of factors that fit in a machine word. This +list is then split into halves, and the product is computed recursively. + +Such splitting is more efficient than repeated N@cross{}1 multiplies since it +forms big multiplies, allowing Karatsuba and higher algorithms to be used. +And even below the Karatsuba threshold a big block of work can be more +efficient for the basecase algorithm. + + +@node Binomial Coefficients Algorithm, Fibonacci Numbers Algorithm, Factorial Algorithm, Other Algorithms +@subsection Binomial Coefficients +@cindex Binomial coefficient algorithm + +Binomial coefficients @m{\left({n}\atop{k}\right), C(n@C{}k)} are calculated +by first arranging @math{k @le{} n/2} using @m{\left({n}\atop{k}\right) = +\left({n}\atop{n-k}\right), C(n@C{}k) = C(n@C{}n-k)} if necessary, and then +evaluating the following product simply from @math{i=2} to @math{i=k}. +@tex +$$ \left({n}\atop{k}\right) = (n-k+1) \prod_{i=2}^{k} {{n-k+i} \over i} $$ +@end tex +@ifnottex + +@example + k (n-k+i) +C(n,k) = (n-k+1) * prod ------- + i=2 i +@end example + +@end ifnottex +It's easy to show that each denominator @math{i} will divide the product so +far, so the exact division algorithm is used (@pxref{Exact Division}). + +The numerators @math{n-k+i} and denominators @math{i} are first accumulated +into as many fit a limb, to save multi-precision operations, though for +@code{mpz_bin_ui} this applies only to the divisors, since @math{n} is an +@code{mpz_t} and @math{n-k+i} in general won't fit in a limb at all. + + +@node Fibonacci Numbers Algorithm, Lucas Numbers Algorithm, Binomial Coefficients Algorithm, Other Algorithms +@subsection Fibonacci Numbers +@cindex Fibonacci number algorithm + +The Fibonacci functions @code{mpz_fib_ui} and @code{mpz_fib2_ui} are designed +for calculating isolated @m{F_n,F[n]} or @m{F_n,F[n]},@m{F_{n-1},F[n-1]} +values efficiently. + +For small @math{n}, a table of single limb values in @code{__gmp_fib_table} is +used. On a 32-bit limb this goes up to @m{F_{47},F[47]}, or on a 64-bit limb +up to @m{F_{93},F[93]}. For convenience the table starts at @m{F_{-1},F[-1]}. + +Beyond the table, values are generated with a binary powering algorithm, +calculating a pair @m{F_n,F[n]} and @m{F_{n-1},F[n-1]} working from high to +low across the bits of @math{n}. The formulas used are +@tex +$$\eqalign{ + F_{2k+1} &= 4F_k^2 - F_{k-1}^2 + 2(-1)^k \cr + F_{2k-1} &= F_k^2 + F_{k-1}^2 \cr + F_{2k} &= F_{2k+1} - F_{2k-1} +}$$ +@end tex +@ifnottex + +@example +F[2k+1] = 4*F[k]^2 - F[k-1]^2 + 2*(-1)^k +F[2k-1] = F[k]^2 + F[k-1]^2 + +F[2k] = F[2k+1] - F[2k-1] +@end example + +@end ifnottex +At each step, @math{k} is the high @math{b} bits of @math{n}. If the next bit +of @math{n} is 0 then @m{F_{2k},F[2k]},@m{F_{2k-1},F[2k-1]} is used, or if +it's a 1 then @m{F_{2k+1},F[2k+1]},@m{F_{2k},F[2k]} is used, and the process +repeated until all bits of @math{n} are incorporated. Notice these formulas +require just two squares per bit of @math{n}. + +It'd be possible to handle the first few @math{n} above the single limb table +with simple additions, using the defining Fibonacci recurrence @m{F_{k+1} = +F_k + F_{k-1}, F[k+1]=F[k]+F[k-1]}, but this is not done since it usually +turns out to be faster for only about 10 or 20 values of @math{n}, and +including a block of code for just those doesn't seem worthwhile. If they +really mattered it'd be better to extend the data table. + +Using a table avoids lots of calculations on small numbers, and makes small +@math{n} go fast. A bigger table would make more small @math{n} go fast, it's +just a question of balancing size against desired speed. For GMP the code is +kept compact, with the emphasis primarily on a good powering algorithm. + +@code{mpz_fib2_ui} returns both @m{F_n,F[n]} and @m{F_{n-1},F[n-1]}, but +@code{mpz_fib_ui} is only interested in @m{F_n,F[n]}. In this case the last +step of the algorithm can become one multiply instead of two squares. One of +the following two formulas is used, according as @math{n} is odd or even. +@tex +$$\eqalign{ + F_{2k} &= F_k (F_k + 2F_{k-1}) \cr + F_{2k+1} &= (2F_k + F_{k-1}) (2F_k - F_{k-1}) + 2(-1)^k +}$$ +@end tex +@ifnottex + +@example +F[2k] = F[k]*(F[k]+2F[k-1]) + +F[2k+1] = (2F[k]+F[k-1])*(2F[k]-F[k-1]) + 2*(-1)^k +@end example + +@end ifnottex +@m{F_{2k+1},F[2k+1]} here is the same as above, just rearranged to be a +multiply. For interest, the @m{2(-1)^k, 2*(-1)^k} term both here and above +can be applied just to the low limb of the calculation, without a carry or +borrow into further limbs, which saves some code size. See comments with +@code{mpz_fib_ui} and the internal @code{mpn_fib2_ui} for how this is done. + + +@node Lucas Numbers Algorithm, Random Number Algorithms, Fibonacci Numbers Algorithm, Other Algorithms +@subsection Lucas Numbers +@cindex Lucas number algorithm + +@code{mpz_lucnum2_ui} derives a pair of Lucas numbers from a pair of Fibonacci +numbers with the following simple formulas. +@tex +$$\eqalign{ + L_k &= F_k + 2F_{k-1} \cr + L_{k-1} &= 2F_k - F_{k-1} +}$$ +@end tex +@ifnottex + +@example +L[k] = F[k] + 2*F[k-1] +L[k-1] = 2*F[k] - F[k-1] +@end example + +@end ifnottex +@code{mpz_lucnum_ui} is only interested in @m{L_n,L[n]}, and some work can be +saved. Trailing zero bits on @math{n} can be handled with a single square +each. +@tex +$$ L_{2k} = L_k^2 - 2(-1)^k $$ +@end tex +@ifnottex + +@example +L[2k] = L[k]^2 - 2*(-1)^k +@end example + +@end ifnottex +And the lowest 1 bit can be handled with one multiply of a pair of Fibonacci +numbers, similar to what @code{mpz_fib_ui} does. +@tex +$$ L_{2k+1} = 5F_{k-1} (2F_k + F_{k-1}) - 4(-1)^k $$ +@end tex +@ifnottex + +@example +L[2k+1] = 5*F[k-1]*(2*F[k]+F[k-1]) - 4*(-1)^k +@end example + +@end ifnottex + + +@node Random Number Algorithms, , Lucas Numbers Algorithm, Other Algorithms +@subsection Random Numbers +@cindex Random number algorithms + +For the @code{urandomb} functions, random numbers are generated simply by +concatenating bits produced by the generator. As long as the generator has +good randomness properties this will produce well-distributed @math{N} bit +numbers. + +For the @code{urandomm} functions, random numbers in a range @math{0@le{}R= ABS(_mp_size)}. When an @code{mpz} routine +is about to (or might be about to) increase @code{_mp_size}, it checks +@code{_mp_alloc} to see whether there's enough space, and reallocates if not. +@code{MPZ_REALLOC} is generally used for this. + +@code{mpz_t} variables initialised with the @code{mpz_roinit_n} function or +the @code{MPZ_ROINIT_N} macro have @code{_mp_alloc = 0} but can have a +non-zero @code{_mp_size}. They can only be used as read-only constants. See +@ref{Integer Special Functions} for details. +@end table + +The various bitwise logical functions like @code{mpz_and} behave as if +negative values were two's complement. But sign and magnitude is always used +internally, and necessary adjustments are made during the calculations. +Sometimes this isn't pretty, but sign and magnitude are best for other +routines. + +Some internal temporary variables are set up with @code{MPZ_TMP_INIT} and these +have @code{_mp_d} space obtained from @code{TMP_ALLOC} rather than the memory +allocation functions. Care is taken to ensure that these are big enough that +no reallocation is necessary (since it would have unpredictable consequences). + +@code{_mp_size} and @code{_mp_alloc} are @code{int}, although @code{mp_size_t} +is usually a @code{long}. This is done to make the fields just 32 bits on +some 64 bits systems, thereby saving a few bytes of data space but still +providing plenty of range. + + +@node Rational Internals, Float Internals, Integer Internals, Internals +@section Rational Internals +@cindex Rational internals + +@code{mpq_t} variables represent rationals using an @code{mpz_t} numerator and +denominator (@pxref{Integer Internals}). + +The canonical form adopted is denominator positive (and non-zero), no common +factors between numerator and denominator, and zero uniquely represented as +0/1. + +It's believed that casting out common factors at each stage of a calculation +is best in general. A GCD is an @math{O(N^2)} operation so it's better to do +a few small ones immediately than to delay and have to do a big one later. +Knowing the numerator and denominator have no common factors can be used for +example in @code{mpq_mul} to make only two cross GCDs necessary, not four. + +This general approach to common factors is badly sub-optimal in the presence +of simple factorizations or little prospect for cancellation, but GMP has no +way to know when this will occur. As per @ref{Efficiency}, that's left to +applications. The @code{mpq_t} framework might still suit, with +@code{mpq_numref} and @code{mpq_denref} for direct access to the numerator and +denominator, or of course @code{mpz_t} variables can be used directly. + + +@node Float Internals, Raw Output Internals, Rational Internals, Internals +@section Float Internals +@cindex Float internals + +Efficient calculation is the primary aim of GMP floats and the use of whole +limbs and simple rounding facilitates this. + +@code{mpf_t} floats have a variable precision mantissa and a single machine +word signed exponent. The mantissa is represented using sign and magnitude. + +@c FIXME: The arrow heads don't join to the lines exactly. +@tex +\global\newdimen\GMPboxwidth \GMPboxwidth=5em +\global\newdimen\GMPboxheight \GMPboxheight=3ex +\def\centreline{\hbox{\raise 0.8ex \vbox{\hrule \hbox{\hfil}}}} +\GMPdisplay{% +\vbox{% + \hbox to 5\GMPboxwidth {most significant limb \hfil least significant limb} + \vskip 0.7ex + \def\GMPcentreline#1{\hbox{\raise 0.5 ex \vbox{\hrule \hbox to #1 {}}}} + \hbox { + \hbox to 3\GMPboxwidth {% + \setbox 0 = \hbox{@code{\_mp\_exp}}% + \dimen0=3\GMPboxwidth + \advance\dimen0 by -\wd0 + \divide\dimen0 by 2 + \advance\dimen0 by -1em + \setbox1 = \hbox{$\rightarrow$}% + \dimen1=\dimen0 + \advance\dimen1 by -\wd1 + \GMPcentreline{\dimen0}% + \hfil + \box0% + \hfil + \GMPcentreline{\dimen1{}}% + \box1} + \hbox to 2\GMPboxwidth {\hfil @code{\_mp\_d}}} + \vskip 0.5ex + \vbox {% + \hrule + \hbox{% + \vrule height 2ex depth 1ex + \hbox to \GMPboxwidth {}% + \vrule + \hbox to \GMPboxwidth {}% + \vrule + \hbox to \GMPboxwidth {}% + \vrule + \hbox to \GMPboxwidth {}% + \vrule + \hbox to \GMPboxwidth {}% + \vrule} + \hrule + } + \hbox {% + \hbox to 0.8 pt {} + \hbox to 3\GMPboxwidth {% + \hfil $\cdot$} \hbox {$\leftarrow$ radix point\hfil}} + \hbox to 5\GMPboxwidth{% + \setbox 0 = \hbox{@code{\_mp\_size}}% + \dimen0 = 5\GMPboxwidth + \advance\dimen0 by -\wd0 + \divide\dimen0 by 2 + \advance\dimen0 by -1em + \dimen1 = \dimen0 + \setbox1 = \hbox{$\leftarrow$}% + \setbox2 = \hbox{$\rightarrow$}% + \advance\dimen0 by -\wd1 + \advance\dimen1 by -\wd2 + \hbox to 0.3 em {}% + \box1 + \GMPcentreline{\dimen0}% + \hfil + \box0 + \hfil + \GMPcentreline{\dimen1}% + \box2} +}} +@end tex +@ifnottex +@example + most least +significant significant + limb limb + + _mp_d + |---- _mp_exp ---> | + _____ _____ _____ _____ _____ + |_____|_____|_____|_____|_____| + . <------------ radix point + + <-------- _mp_size ---------> +@sp 1 +@end example +@end ifnottex + +@noindent +The fields are as follows. + +@table @asis +@item @code{_mp_size} +The number of limbs currently in use, or the negative of that when +representing a negative value. Zero is represented by @code{_mp_size} and +@code{_mp_exp} both set to zero, and in that case the @code{_mp_d} data is +unused. (In the future @code{_mp_exp} might be undefined when representing +zero.) + +@item @code{_mp_prec} +The precision of the mantissa, in limbs. In any calculation the aim is to +produce @code{_mp_prec} limbs of result (the most significant being non-zero). + +@item @code{_mp_d} +A pointer to the array of limbs which is the absolute value of the mantissa. +These are stored ``little endian'' as per the @code{mpn} functions, so +@code{_mp_d[0]} is the least significant limb and +@code{_mp_d[ABS(_mp_size)-1]} the most significant. + +The most significant limb is always non-zero, but there are no other +restrictions on its value, in particular the highest 1 bit can be anywhere +within the limb. + +@code{_mp_prec+1} limbs are allocated to @code{_mp_d}, the extra limb being +for convenience (see below). There are no reallocations during a calculation, +only in a change of precision with @code{mpf_set_prec}. + +@item @code{_mp_exp} +The exponent, in limbs, determining the location of the implied radix point. +Zero means the radix point is just above the most significant limb. Positive +values mean a radix point offset towards the lower limbs and hence a value +@math{@ge{} 1}, as for example in the diagram above. Negative exponents mean +a radix point further above the highest limb. + +Naturally the exponent can be any value, it doesn't have to fall within the +limbs as the diagram shows, it can be a long way above or a long way below. +Limbs other than those included in the @code{@{_mp_d,_mp_size@}} data +are treated as zero. +@end table + +The @code{_mp_size} and @code{_mp_prec} fields are @code{int}, although the +@code{mp_size_t} type is usually a @code{long}. The @code{_mp_exp} field is +usually @code{long}. This is done to make some fields just 32 bits on some 64 +bits systems, thereby saving a few bytes of data space but still providing +plenty of precision and a very large range. + + +@sp 1 +@noindent +The following various points should be noted. + +@table @asis +@item Low Zeros +The least significant limbs @code{_mp_d[0]} etc can be zero, though such low +zeros can always be ignored. Routines likely to produce low zeros check and +avoid them to save time in subsequent calculations, but for most routines +they're quite unlikely and aren't checked. + +@item Mantissa Size Range +The @code{_mp_size} count of limbs in use can be less than @code{_mp_prec} if +the value can be represented in less. This means low precision values or +small integers stored in a high precision @code{mpf_t} can still be operated +on efficiently. + +@code{_mp_size} can also be greater than @code{_mp_prec}. Firstly a value is +allowed to use all of the @code{_mp_prec+1} limbs available at @code{_mp_d}, +and secondly when @code{mpf_set_prec_raw} lowers @code{_mp_prec} it leaves +@code{_mp_size} unchanged and so the size can be arbitrarily bigger than +@code{_mp_prec}. + +@item Rounding +All rounding is done on limb boundaries. Calculating @code{_mp_prec} limbs +with the high non-zero will ensure the application requested minimum precision +is obtained. + +The use of simple ``trunc'' rounding towards zero is efficient, since there's +no need to examine extra limbs and increment or decrement. + +@item Bit Shifts +Since the exponent is in limbs, there are no bit shifts in basic operations +like @code{mpf_add} and @code{mpf_mul}. When differing exponents are +encountered all that's needed is to adjust pointers to line up the relevant +limbs. + +Of course @code{mpf_mul_2exp} and @code{mpf_div_2exp} will require bit shifts, +but the choice is between an exponent in limbs which requires shifts there, or +one in bits which requires them almost everywhere else. + +@item Use of @code{_mp_prec+1} Limbs +The extra limb on @code{_mp_d} (@code{_mp_prec+1} rather than just +@code{_mp_prec}) helps when an @code{mpf} routine might get a carry from its +operation. @code{mpf_add} for instance will do an @code{mpn_add} of +@code{_mp_prec} limbs. If there's no carry then that's the result, but if +there is a carry then it's stored in the extra limb of space and +@code{_mp_size} becomes @code{_mp_prec+1}. + +Whenever @code{_mp_prec+1} limbs are held in a variable, the low limb is not +needed for the intended precision, only the @code{_mp_prec} high limbs. But +zeroing it out or moving the rest down is unnecessary. Subsequent routines +reading the value will simply take the high limbs they need, and this will be +@code{_mp_prec} if their target has that same precision. This is no more than +a pointer adjustment, and must be checked anyway since the destination +precision can be different from the sources. + +Copy functions like @code{mpf_set} will retain a full @code{_mp_prec+1} limbs +if available. This ensures that a variable which has @code{_mp_size} equal to +@code{_mp_prec+1} will get its full exact value copied. Strictly speaking +this is unnecessary since only @code{_mp_prec} limbs are needed for the +application's requested precision, but it's considered that an @code{mpf_set} +from one variable into another of the same precision ought to produce an exact +copy. + +@item Application Precisions +@code{__GMPF_BITS_TO_PREC} converts an application requested precision to an +@code{_mp_prec}. The value in bits is rounded up to a whole limb then an +extra limb is added since the most significant limb of @code{_mp_d} is only +non-zero and therefore might contain only one bit. + +@code{__GMPF_PREC_TO_BITS} does the reverse conversion, and removes the extra +limb from @code{_mp_prec} before converting to bits. The net effect of +reading back with @code{mpf_get_prec} is simply the precision rounded up to a +multiple of @code{mp_bits_per_limb}. + +Note that the extra limb added here for the high only being non-zero is in +addition to the extra limb allocated to @code{_mp_d}. For example with a +32-bit limb, an application request for 250 bits will be rounded up to 8 +limbs, then an extra added for the high being only non-zero, giving an +@code{_mp_prec} of 9. @code{_mp_d} then gets 10 limbs allocated. Reading +back with @code{mpf_get_prec} will take @code{_mp_prec} subtract 1 limb and +multiply by 32, giving 256 bits. + +Strictly speaking, the fact that the high limb has at least one bit means that a +float with, say, 3 limbs of 32-bits each will be holding at least 65 bits, but +for the purposes of @code{mpf_t} it's considered simply to be 64 bits, a nice +multiple of the limb size. +@end table + + +@node Raw Output Internals, C++ Interface Internals, Float Internals, Internals +@section Raw Output Internals +@cindex Raw output internals + +@noindent +@code{mpz_out_raw} uses the following format. + +@tex +\global\newdimen\GMPboxwidth \GMPboxwidth=5em +\global\newdimen\GMPboxheight \GMPboxheight=3ex +\def\centreline{\hbox{\raise 0.8ex \vbox{\hrule \hbox{\hfil}}}} +\GMPdisplay{% +\vbox{% + \def\GMPcentreline#1{\hbox{\raise 0.5 ex \vbox{\hrule \hbox to #1 {}}}} + \vbox {% + \hrule + \hbox{% + \vrule height 2.5ex depth 1.5ex + \hbox to \GMPboxwidth {\hfil size\hfil}% + \vrule + \hbox to 3\GMPboxwidth {\hfil data bytes\hfil}% + \vrule} + \hrule} +}} +@end tex +@ifnottex +@example ++------+------------------------+ +| size | data bytes | ++------+------------------------+ +@end example +@end ifnottex + +The size is 4 bytes written most significant byte first, being the number of +subsequent data bytes, or the two's complement negative of that when a negative +integer is represented. The data bytes are the absolute value of the integer, +written most significant byte first. + +The most significant data byte is always non-zero, so the output is the same +on all systems, irrespective of limb size. + +In GMP 1, leading zero bytes were written to pad the data bytes to a multiple +of the limb size. @code{mpz_inp_raw} will still accept this, for +compatibility. + +The use of ``big endian'' for both the size and data fields is deliberate, it +makes the data easy to read in a hex dump of a file. Unfortunately it also +means that the limb data must be reversed when reading or writing, so neither +a big endian nor little endian system can just read and write @code{_mp_d}. + + +@node C++ Interface Internals, , Raw Output Internals, Internals +@section C++ Interface Internals +@cindex C++ interface internals + +A system of expression templates is used to ensure something like @code{a=b+c} +turns into a simple call to @code{mpz_add} etc. For @code{mpf_class} +the scheme also ensures the precision of the final +destination is used for any temporaries within a statement like +@code{f=w*x+y*z}. These are important features which a naive implementation +cannot provide. + +A simplified description of the scheme follows. The true scheme is +complicated by the fact that expressions have different return types. For +detailed information, refer to the source code. + +To perform an operation, say, addition, we first define a ``function object'' +evaluating it, + +@example +struct __gmp_binary_plus +@{ + static void eval(mpf_t f, const mpf_t g, const mpf_t h) + @{ + mpf_add(f, g, h); + @} +@}; +@end example + +@noindent +And an ``additive expression'' object, + +@example +__gmp_expr<__gmp_binary_expr > +operator+(const mpf_class &f, const mpf_class &g) +@{ + return __gmp_expr + <__gmp_binary_expr >(f, g); +@} +@end example + +The seemingly redundant @code{__gmp_expr<__gmp_binary_expr<@dots{}>>} is used to +encapsulate any possible kind of expression into a single template type. In +fact even @code{mpf_class} etc are @code{typedef} specializations of +@code{__gmp_expr}. + +Next we define assignment of @code{__gmp_expr} to @code{mpf_class}. + +@example +template +mpf_class & mpf_class::operator=(const __gmp_expr &expr) +@{ + expr.eval(this->get_mpf_t(), this->precision()); + return *this; +@} + +template +void __gmp_expr<__gmp_binary_expr >::eval +(mpf_t f, mp_bitcnt_t precision) +@{ + Op::eval(f, expr.val1.get_mpf_t(), expr.val2.get_mpf_t()); +@} +@end example + +where @code{expr.val1} and @code{expr.val2} are references to the expression's +operands (here @code{expr} is the @code{__gmp_binary_expr} stored within the +@code{__gmp_expr}). + +This way, the expression is actually evaluated only at the time of assignment, +when the required precision (that of @code{f}) is known. Furthermore the +target @code{mpf_t} is now available, thus we can call @code{mpf_add} directly +with @code{f} as the output argument. + +Compound expressions are handled by defining operators taking subexpressions +as their arguments, like this: + +@example +template +__gmp_expr +<__gmp_binary_expr<__gmp_expr, __gmp_expr, __gmp_binary_plus> > +operator+(const __gmp_expr &expr1, const __gmp_expr &expr2) +@{ + return __gmp_expr + <__gmp_binary_expr<__gmp_expr, __gmp_expr, __gmp_binary_plus> > + (expr1, expr2); +@} +@end example + +And the corresponding specializations of @code{__gmp_expr::eval}: + +@example +template +void __gmp_expr +<__gmp_binary_expr<__gmp_expr, __gmp_expr, Op> >::eval +(mpf_t f, mp_bitcnt_t precision) +@{ + // declare two temporaries + mpf_class temp1(expr.val1, precision), temp2(expr.val2, precision); + Op::eval(f, temp1.get_mpf_t(), temp2.get_mpf_t()); +@} +@end example + +The expression is thus recursively evaluated to any level of complexity and +all subexpressions are evaluated to the precision of @code{f}. + + +@node Contributors, References, Internals, Top +@comment node-name, next, previous, up +@appendix Contributors +@cindex Contributors + +Torbj@"orn Granlund wrote the original GMP library and is still the main +developer. Code not explicitly attributed to others was contributed by +Torbj@"orn. Several other individuals and organizations have contributed +GMP. Here is a list in chronological order on first contribution: + +Gunnar Sj@"odin and Hans Riesel helped with mathematical problems in early +versions of the library. + +Richard Stallman helped with the interface design and revised the first +version of this manual. + +Brian Beuning and Doug Lea helped with testing of early versions of the +library and made creative suggestions. + +John Amanatides of York University in Canada contributed the function +@code{mpz_probab_prime_p}. + +Paul Zimmermann wrote the REDC-based mpz_powm code, the Sch@"onhage-Strassen +FFT multiply code, and the Karatsuba square root code. He also improved the +Toom3 code for GMP 4.2. Paul sparked the development of GMP 2, with his +comparisons between bignum packages. The ECMNET project Paul is organizing +was a driving force behind many of the optimizations in GMP 3. Paul also +wrote the new GMP 4.3 nth root code (with Torbj@"orn). + +Ken Weber (Kent State University, Universidade Federal do Rio Grande do Sul) +contributed now defunct versions of @code{mpz_gcd}, @code{mpz_divexact}, +@code{mpn_gcd}, and @code{mpn_bdivmod}, partially supported by CNPq (Brazil) +grant 301314194-2. + +Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' configure. +He has also made valuable suggestions and tested numerous intermediary +releases. + +Joachim Hollman was involved in the design of the @code{mpf} interface, and in +the @code{mpz} design revisions for version 2. + +Bennet Yee contributed the initial versions of @code{mpz_jacobi} and +@code{mpz_legendre}. + +Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and +@file{mpn/m68k/rshift.S} (now in @file{.asm} form). + +Robert Harley of Inria, France and David Seal of ARM, England, suggested clever +improvements for population count. Robert also wrote highly optimized +Karatsuba and 3-way Toom multiplication functions for GMP 3, and contributed +the ARM assembly code. + +Torsten Ekedahl of the Mathematical Department of Stockholm University provided +significant inspiration during several phases of the GMP development. His +mathematical expertise helped improve several algorithms. + +Linus Nordberg wrote the new configure system based on autoconf and +implemented the new random functions. + +Kevin Ryde worked on a large number of things: optimized x86 code, m4 asm +macros, parameter tuning, speed measuring, the configure system, function +inlining, divisibility tests, bit scanning, Jacobi symbols, Fibonacci and Lucas +number functions, printf and scanf functions, perl interface, demo expression +parser, the algorithms chapter in the manual, @file{gmpasm-mode.el}, and +various miscellaneous improvements elsewhere. + +Kent Boortz made the Mac OS 9 port. + +Steve Root helped write the optimized alpha 21264 assembly code. + +Gerardo Ballabio wrote the @file{gmpxx.h} C++ class interface and the C++ +@code{istream} input routines. + +Jason Moxham rewrote @code{mpz_fac_ui}. + +Pedro Gimeno implemented the Mersenne Twister and made other random number +improvements. + +Niels M@"oller wrote the sub-quadratic GCD, extended GCD and Jacobi code, the +quadratic Hensel division code, and (with Torbj@"orn) the new divide and +conquer division code for GMP 4.3. Niels also helped implement the new Toom +multiply code for GMP 4.3 and implemented helper functions to simplify Toom +evaluations for GMP 5.0. He wrote the original version of mpn_mulmod_bnm1, and +he is the main author of the mini-gmp package used for gmp bootstrapping. + +Alberto Zanoni and Marco Bodrato suggested the unbalanced multiply strategy, +and found the optimal strategies for evaluation and interpolation in Toom +multiplication. + +Marco Bodrato helped implement the new Toom multiply code for GMP 4.3 and +implemented most of the new Toom multiply and squaring code for 5.0. +He is the main author of the current mpn_mulmod_bnm1, mpn_mullo_n, and +mpn_sqrlo. Marco also wrote the functions mpn_invert and mpn_invertappr, +and improved the speed of integer root extraction. He is the author of +mini-mpq, an additional layer to mini-gmp; of most of the combinatorial +functions and the BPSW primality testing implementation, for both the +main library and the mini-gmp package. + +David Harvey suggested the internal function @code{mpn_bdiv_dbm1}, implementing +division relevant to Toom multiplication. He also worked on fast assembly +sequences, in particular on a fast AMD64 @code{mpn_mul_basecase}. He wrote +the internal middle product functions @code{mpn_mulmid_basecase}, +@code{mpn_toom42_mulmid}, @code{mpn_mulmid_n} and related helper routines. + +Martin Boij wrote @code{mpn_perfect_power_p}. + +Marc Glisse improved @file{gmpxx.h}: use fewer temporaries (faster), +specializations of @code{numeric_limits} and @code{common_type}, C++11 +features (move constructors, explicit bool conversion, UDL), make the +conversion from @code{mpq_class} to @code{mpz_class} explicit, optimize +operations where one argument is a small compile-time constant, replace +some heap allocations by stack allocations. He also fixed the eofbit +handling of C++ streams, and removed one division from @file{mpq/aors.c}. + +David S Miller wrote assembly code for SPARC T3 and T4. + +Mark Sofroniou cleaned up the types of mul_fft.c, letting it work for huge +operands. + +Ulrich Weigand ported GMP to the powerpc64le ABI. + +(This list is chronological, not ordered after significance. If you have +contributed to GMP but are not listed above, please tell +@email{gmp-devel@@gmplib.org} about the omission!) + +The development of floating point functions of GNU MP 2 was supported in part +by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO (POlynomial +System SOlving). + +The development of GMP 2, 3, and 4.0 was supported in part by the IDA Center +for Computing Sciences. + +The development of GMP 4.3, 5.0, and 5.1 was supported in part by the Swedish +Foundation for Strategic Research. + +Thanks go to Hans Thorsen for donating an SGI system for the GMP test system +environment. + +@node References, GNU Free Documentation License, Contributors, Top +@comment node-name, next, previous, up +@appendix References +@cindex References + +@c FIXME: In tex, the @uref's are unhyphenated, which is good for clarity, +@c but being long words they upset paragraph formatting (the preceding line +@c can get badly stretched). Would like an conditional @* style line break +@c if the uref is too long to fit on the last line of the paragraph, but it's +@c not clear how to do that. For now explicit @texlinebreak{}s are used on +@c paragraphs that come out bad. + +@section Books + +@itemize @bullet +@item +Jonathan M. Borwein and Peter B. Borwein, ``Pi and the AGM: A Study in +Analytic Number Theory and Computational Complexity'', Wiley, 1998. + +@item +Richard Crandall and Carl Pomerance, ``Prime Numbers: A Computational +Perspective'', 2nd edition, Springer-Verlag, 2005. +@texlinebreak{} @uref{https://www.math.dartmouth.edu/~carlp/} + +@item +Henri Cohen, ``A Course in Computational Algebraic Number Theory'', Graduate +Texts in Mathematics number 138, Springer-Verlag, 1993. +@texlinebreak{} @uref{https://www.math.u-bordeaux.fr/~cohen/} + +@item +Donald E. Knuth, ``The Art of Computer Programming'', volume 2, +``Seminumerical Algorithms'', 3rd edition, Addison-Wesley, 1998. +@texlinebreak{} @uref{https://www-cs-faculty.stanford.edu/~knuth/taocp.html} + +@item +John D. Lipson, ``Elements of Algebra and Algebraic Computing'', +The Benjamin Cummings Publishing Company Inc, 1981. + +@item +Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, ``Handbook of +Applied Cryptography'', @uref{http://www.cacr.math.uwaterloo.ca/hac/} + +@item +Richard M. Stallman and the GCC Developer Community, ``Using the GNU Compiler +Collection'', Free Software Foundation, 2008, available online +@uref{https://gcc.gnu.org/onlinedocs/}, and in the GCC package +@uref{https://ftp.gnu.org/gnu/gcc/} +@end itemize + +@section Papers + +@itemize @bullet +@item +Yves Bertot, Nicolas Magaud and Paul Zimmermann, ``A Proof of GMP Square +Root'', Journal of Automated Reasoning, volume 29, 2002, pp.@: 225-252. Also +available online as INRIA Research Report 4475, June 2002, +@uref{https://hal.inria.fr/docs/00/07/21/13/PDF/RR-4475.pdf} + +@item +Christoph Burnikel and Joachim Ziegler, ``Fast Recursive Division'', +Max-Planck-Institut fuer Informatik Research Report MPI-I-98-1-022, +@texlinebreak{} @uref{https://www.mpi-inf.mpg.de/~ziegler/TechRep.ps.gz} + +@item +Torbj@"orn Granlund and Peter L. Montgomery, ``Division by Invariant Integers +using Multiplication'', in Proceedings of the SIGPLAN PLDI'94 Conference, June +1994. Also available @uref{https://gmplib.org/~tege/divcnst-pldi94.pdf}. + +@item +Niels M@"oller and Torbj@"orn Granlund, ``Improved division by invariant +integers'', IEEE Transactions on Computers, 11 June 2010. +@uref{https://gmplib.org/~tege/division-paper.pdf} + +@item +Torbj@"orn Granlund and Niels M@"oller, ``Division of integers large and +small'', to appear. + +@item +Tudor Jebelean, +``An algorithm for exact division'', +Journal of Symbolic Computation, +volume 15, 1993, pp.@: 169-180. +Research report version available @texlinebreak{} +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-35.ps.gz} + +@item +Tudor Jebelean, ``Exact Division with Karatsuba Complexity - Extended +Abstract'', RISC-Linz technical report 96-31, @texlinebreak{} +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1996/96-31.ps.gz} + +@item +Tudor Jebelean, ``Practical Integer Division with Karatsuba Complexity'', +ISSAC 97, pp.@: 339-341. Technical report available @texlinebreak{} +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1996/96-29.ps.gz} + +@item +Tudor Jebelean, ``A Generalization of the Binary GCD Algorithm'', ISSAC 93, +pp.@: 111-116. Technical report version available @texlinebreak{} +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1993/93-01.ps.gz} + +@item +Tudor Jebelean, ``A Double-Digit Lehmer-Euclid Algorithm for Finding the GCD +of Long Integers'', Journal of Symbolic Computation, volume 19, 1995, +pp.@: 145-157. Technical report version also available @texlinebreak{} +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-69.ps.gz} + +@item +Werner Krandick and Tudor Jebelean, ``Bidirectional Exact Integer Division'', +Journal of Symbolic Computation, volume 21, 1996, pp.@: 441-455. Early +technical report version also available +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1994/94-50.ps.gz} + +@item +Makoto Matsumoto and Takuji Nishimura, ``Mersenne Twister: A 623-dimensionally +equidistributed uniform pseudorandom number generator'', ACM Transactions on +Modelling and Computer Simulation, volume 8, January 1998, pp.@: 3-30. +Available online @texlinebreak{} +@uref{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/mt.pdf} + +@item +R. Moenck and A. Borodin, ``Fast Modular Transforms via Division'', +Proceedings of the 13th Annual IEEE Symposium on Switching and Automata +Theory, October 1972, pp.@: 90-96. Reprinted as ``Fast Modular Transforms'', +Journal of Computer and System Sciences, volume 8, number 3, June 1974, +pp.@: 366-386. + +@item +Niels M@"oller, ``On Sch@"onhage's algorithm and subquadratic integer GCD + computation'', in Mathematics of Computation, volume 77, January 2008, pp.@: + 589-607, @uref{https://www.ams.org/journals/mcom/2008-77-261/S0025-5718-07-02017-0/home.html} + +@item +Peter L. Montgomery, ``Modular Multiplication Without Trial Division'', in +Mathematics of Computation, volume 44, number 170, April 1985. + +@item +Arnold Sch@"onhage and Volker Strassen, ``Schnelle Multiplikation grosser +Zahlen'', Computing 7, 1971, pp.@: 281-292. + +@item +Kenneth Weber, ``The accelerated integer GCD algorithm'', +ACM Transactions on Mathematical Software, +volume 21, number 1, March 1995, pp.@: 111-122. + +@item +Paul Zimmermann, ``Karatsuba Square Root'', INRIA Research Report 3805, +November 1999, @uref{https://hal.inria.fr/inria-00072854/PDF/RR-3805.pdf} + +@item +Paul Zimmermann, ``A Proof of GMP Fast Division and Square Root +Implementations'', @texlinebreak{} +@uref{https://homepages.loria.fr/PZimmermann/papers/proof-div-sqrt.ps.gz} + +@item +Dan Zuras, ``On Squaring and Multiplying Large Integers'', ARITH-11: IEEE +Symposium on Computer Arithmetic, 1993, pp.@: 260 to 271. Reprinted as ``More +on Multiplying and Squaring Large Integers'', IEEE Transactions on Computers, +volume 43, number 8, August 1994, pp.@: 899-908. + +@item +Niels M@"oller, ``Efficient computation of the Jacobi symbol'', @texlinebreak{} +@uref{https://arxiv.org/abs/1907.07795} +@end itemize + +@node GNU Free Documentation License, Concept Index, References, Top +@appendix GNU Free Documentation License +@cindex GNU Free Documentation License +@cindex Free Documentation License +@cindex Documentation license +@include fdl-1.3.texi + + +@node Concept Index, Function Index, GNU Free Documentation License, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp + +@node Function Index, , Concept Index, Top +@comment node-name, next, previous, up +@unnumbered Function and Type Index +@printindex fn + +@bye + +@c Local variables: +@c fill-column: 78 +@c compile-command: "make gmp.info" +@c End: diff --git a/gmp-6.3.0/doc/isa_abi_headache b/gmp-6.3.0/doc/isa_abi_headache new file mode 100644 index 0000000..7e1430d --- /dev/null +++ b/gmp-6.3.0/doc/isa_abi_headache @@ -0,0 +1,128 @@ +Copyright 2000 Free Software Foundation, Inc. + +This file is part of the GNU MP Library. + +The GNU MP Library is free software; you can redistribute it and/or modify +it under the terms of either: + + * the GNU Lesser General Public License as published by the Free + Software Foundation; either version 3 of the License, or (at your + option) any later version. + +or + + * the GNU General Public License as published by the Free Software + Foundation; either version 2 of the License, or (at your option) any + later version. + +or both in parallel, as here. + +The GNU MP Library is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for more details. + +You should have received copies of the GNU General Public License and the +GNU Lesser General Public License along with the GNU MP Library. If not, +see https://www.gnu.org/licenses/. + + + + +Terms Used In This Document: + ISA = Instruction Set Architecture. The instructions the current + processor provides. + ABI = Application Binary Interface. Specifies calling convention, + type sizes, etc. + AR64 = Arithmetic operations are 64-bit using 64-bit instructions + (E.g., addition, subtraction, load, store, of 64-bit integer types + are done with single instructions, not 32 bits at a time.) + Environment = The operating system and compiler. + +GMP is a very complex package to build since its speed is very +sensitive to the ISA and ABI. For example, if the ISA provides 64-bit +instructions, it is crucial that GMP is configured to use them. + +Most environments that run on a 64-bit ISA provide more than one ABI. +Typically one of the supported ABI's is a backward compatible 32-bit +ABI, and one ABI provides 64-bit addressing and `long' (sometimes +known as LP64). But a few environments (IRIX, HP-UX) provide +intermediate ABI's using 32-bit addressing but allow efficient 64-bit +operations through a `long long' type. For the latter to be useful to +GMP, the ABI must allow operations using the native 64-bit +instructions provided by the ISA, and allow passing of 64-bit +quantities atomically. + +The ABI is typically chosen by means of command line options to the +compiler tools (gcc, cc, c89, nm, ar, ld, as). Different environments +use different defaults, but as of this writing (May 2000) the +dominating default is to the plain 32-bit ABI in its most arcane form. + +The GMP 3.0.x approach was to compile using the ABI that gives the +best performance. That places the burden on users to pass special +options to the compiler when they compile their GMP applications. +That approach has its advantages and disadvantages. The main +advantage is that users don't unknowingly get bad GMP performance. +The main disadvantage is that users' compiles (actually links) will +fail unless they pass special compiler options. + +** SPARC + +System vendors often confuse ABI, ISA, and implementation. The worst +case is Solaris, were the unbundled compiler confuses ISA and ABI, and +the options have very confusing names. + + option interpretation + ====== ============== +cc -xarch=v8plus ISA=sparcv9, ABI=V8plus (PTR=32, see below) +gcc -mv8plus ISA=sparcv9, ABI=V8plus (see below) +cc -xarch=v9 ISA=sparcv9, ABI=V9 (implying AR=64, PTR=64) + +It's hard to believe, but the option v8plus really means ISA=V9! + +Solaris releases prior to version 7 running on a V9 CPU fails to +save/restore the upper 32 bits of the `i' and `l' registers. The +`v8plus' option generates code that use as many V9 features as +possible under such circumstances. + +** MIPS + +The IRIX 6 compilers gets things right. They have a clear +understanding of the differences between ABI and ISA. The option +names are descriptive. + + option interpretation + ====== ============== +cc -n32 ABI=n32 (implying AR=64, PTR=32) +gcc -mabi=n32 ABI=n32 (implying AR=64, PTR=32) +cc -64 ABI=64 (implying AR=64, PTR=64) +gcc -mabi=64 ABI=64 (implying AR=64, PTR=64) +cc -mips3 ISA=mips3 +gcc -mips3 ISA=mips3 +cc -mips4 ISA=mips4 +gcc -mips4 ISA=mips4 + +** HP-PA + +HP-UX is somewhat weird, but not as broken as Solaris. + + option interpretation + ====== ============== +cc +DA2.0 ABI=32bit (implying AR=64, PTR=32) +cc +DD64 ABI=64bit (implying AR=64, PTR=64) + +Code performing 64-bit arithmetic in the HP-UX 32-bit is not +compatible with the 64-bit ABI; the former has a calling convention +that passes/returns 64-bit integer quantities as two 32-bit chunks. + +** PowerPC + +While the PowerPC ABI's are capable of supporting 64-bit +registers/operations, the compilers under AIX are similar to Solaris' +cc in that they don't currently provide any 32-bit addressing with +64-bit arithmetic. + + option interpretation + ====== ============== +cc -q64 ABI=64bit (implying AR=64, PTR=64) +gcc -maix64 -mpowerpc64 ABI=64bit (implying AR=64, PTR=64) diff --git a/gmp-6.3.0/doc/mdate-sh b/gmp-6.3.0/doc/mdate-sh new file mode 100755 index 0000000..e8dfaca --- /dev/null +++ b/gmp-6.3.0/doc/mdate-sh @@ -0,0 +1,224 @@ +#!/bin/sh +# Get modification time of a file or directory and pretty-print it. + +scriptversion=2010-08-21.06; # UTC + +# Copyright (C) 1995-2014 Free Software Foundation, Inc. +# written by Ulrich Drepper , June 1995 +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# This file is maintained in Automake, please report +# bugs to or send patches to +# . + +if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then + emulate sh + NULLCMD=: + # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +fi + +case $1 in + '') + echo "$0: No file. Try '$0 --help' for more information." 1>&2 + exit 1; + ;; + -h | --h*) + cat <<\EOF +Usage: mdate-sh [--help] [--version] FILE + +Pretty-print the modification day of FILE, in the format: +1 January 1970 + +Report bugs to . +EOF + exit $? + ;; + -v | --v*) + echo "mdate-sh $scriptversion" + exit $? + ;; +esac + +error () +{ + echo "$0: $1" >&2 + exit 1 +} + + +# Prevent date giving response in another language. +LANG=C +export LANG +LC_ALL=C +export LC_ALL +LC_TIME=C +export LC_TIME + +# GNU ls changes its time format in response to the TIME_STYLE +# variable. Since we cannot assume 'unset' works, revert this +# variable to its documented default. +if test "${TIME_STYLE+set}" = set; then + TIME_STYLE=posix-long-iso + export TIME_STYLE +fi + +save_arg1=$1 + +# Find out how to get the extended ls output of a file or directory. +if ls -L /dev/null 1>/dev/null 2>&1; then + ls_command='ls -L -l -d' +else + ls_command='ls -l -d' +fi +# Avoid user/group names that might have spaces, when possible. +if ls -n /dev/null 1>/dev/null 2>&1; then + ls_command="$ls_command -n" +fi + +# A 'ls -l' line looks as follows on OS/2. +# drwxrwx--- 0 Aug 11 2001 foo +# This differs from Unix, which adds ownership information. +# drwxrwx--- 2 root root 4096 Aug 11 2001 foo +# +# To find the date, we split the line on spaces and iterate on words +# until we find a month. This cannot work with files whose owner is a +# user named "Jan", or "Feb", etc. However, it's unlikely that '/' +# will be owned by a user whose name is a month. So we first look at +# the extended ls output of the root directory to decide how many +# words should be skipped to get the date. + +# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. +set x`$ls_command /` + +# Find which argument is the month. +month= +command= +until test $month +do + test $# -gt 0 || error "failed parsing '$ls_command /' output" + shift + # Add another shift to the command. + command="$command shift;" + case $1 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; + esac +done + +test -n "$month" || error "failed parsing '$ls_command /' output" + +# Get the extended ls output of the file or directory. +set dummy x`eval "$ls_command \"\\\$save_arg1\""` + +# Remove all preceding arguments +eval $command + +# Because of the dummy argument above, month is in $2. +# +# On a POSIX system, we should have +# +# $# = 5 +# $1 = file size +# $2 = month +# $3 = day +# $4 = year or time +# $5 = filename +# +# On Darwin 7.7.0 and 7.6.0, we have +# +# $# = 4 +# $1 = day +# $2 = month +# $3 = year or time +# $4 = filename + +# Get the month. +case $2 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; +esac + +case $3 in + ???*) day=$1;; + *) day=$3; shift;; +esac + +# Here we have to deal with the problem that the ls output gives either +# the time of day or the year. +case $3 in + *:*) set `date`; eval year=\$$# + case $2 in + Jan) nummonthtod=1;; + Feb) nummonthtod=2;; + Mar) nummonthtod=3;; + Apr) nummonthtod=4;; + May) nummonthtod=5;; + Jun) nummonthtod=6;; + Jul) nummonthtod=7;; + Aug) nummonthtod=8;; + Sep) nummonthtod=9;; + Oct) nummonthtod=10;; + Nov) nummonthtod=11;; + Dec) nummonthtod=12;; + esac + # For the first six month of the year the time notation can also + # be used for files modified in the last year. + if (expr $nummonth \> $nummonthtod) > /dev/null; + then + year=`expr $year - 1` + fi;; + *) year=$3;; +esac + +# The result. +echo $day $month $year + +# Local Variables: +# mode: shell-script +# sh-indentation: 2 +# eval: (add-hook 'write-file-hooks 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H" +# time-stamp-time-zone: "UTC" +# time-stamp-end: "; # UTC" +# End: diff --git a/gmp-6.3.0/doc/projects.html b/gmp-6.3.0/doc/projects.html new file mode 100644 index 0000000..34bbb52 --- /dev/null +++ b/gmp-6.3.0/doc/projects.html @@ -0,0 +1,476 @@ + + + + GMP Development Projects + + + + + +
+

+ GMP Development Projects +

+
+ + +
+Copyright 2000-2006, 2008-2011 Free Software Foundation, Inc.
+
+This file is part of the GNU MP Library.
+
+The GNU MP Library is free software; you can redistribute it and/or modify
+it under the terms of either:
+
+  * the GNU Lesser General Public License as published by the Free
+    Software Foundation; either version 3 of the License, or (at your
+    option) any later version.
+
+or
+
+  * the GNU General Public License as published by the Free Software
+    Foundation; either version 2 of the License, or (at your option) any
+    later version.
+
+or both in parallel, as here.
+
+The GNU MP Library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received copies of the GNU General Public License and the
+GNU Lesser General Public License along with the GNU MP Library.  If not,
+see https://www.gnu.org/licenses/.
+
+ + +
+ + This file current as of 29 Jan 2014. An up-to-date version is available at + https://gmplib.org/projects.html. + Please send comments about this page to gmp-devel@gmplib.org. + +

This file lists projects suitable for volunteers. Please see the + tasks file for smaller tasks. + +

If you want to work on any of the projects below, please let + gmp-devel@gmplib.org know. If you want to help with a project + that already somebody else is working on, you will get in touch through + gmp-devel@gmplib.org. (There are no email addresses of + volunteers below, due to spamming problems.) + +

    +
  • Faster multiplication + +
      + +
    1. Work on the algorithm selection code for unbalanced multiplication. + +
    2. Implement an FFT variant computing the coefficients mod m different + limb size primes of the form l*2^k+1. i.e., compute m separate FFTs. + The wanted coefficients will at the end be found by lifting with CRT + (Chinese Remainder Theorem). If we let m = 3, i.e., use 3 primes, we + can split the operands into coefficients at limb boundaries, and if + our machine uses b-bit limbs, we can multiply numbers with close to + 2^b limbs without coefficient overflow. For smaller multiplication, + we might perhaps let m = 1, and instead of splitting our operands at + limb boundaries, split them in much smaller pieces. We might also use + 4 or more primes, and split operands into bigger than b-bit chunks. + By using more primes, the gain in shorter transform length, but lose + in having to do more FFTs, but that is a slight total save. We then + lose in more expensive CRT.

      + +

      [We now have two implementations of this algorithm, one by Tommy + Färnqvist and one by Niels Möller.] + +

    3. Work on short products. Our mullo and mulmid are probably K, but we + lack mulhi. + +
    + +

    Another possibility would be an optimized cube. In the basecase that + should definitely be able to save cross-products in a similar fashion to + squaring, but some investigation might be needed for how best to adapt + the higher-order algorithms. Not sure whether cubing or further small + powers have any particularly important uses though. + + +

  • Assembly routines + +

    Write new and improve existing assembly routines. The tests/devel + programs and the tune/speed.c and tune/many.pl programs are useful for + testing and timing the routines you write. See the README files in those + directories for more information. + +

    Please make sure your new routines are fast for these three situations: +

      +
    1. Small operands of less than, say, 10 limbs. +
    2. Medium size operands, that fit into the cache. +
    3. Huge operands that does not fit into the cache. +
    + +

    The most important routines are mpn_addmul_1, mpn_mul_basecase and + mpn_sqr_basecase. The latter two don't exist for all machines, while + mpn_addmul_1 exists for almost all machines. + +

    Standard techniques for these routines are unrolling, software + pipelining, and specialization for common operand values. For machines + with poor integer multiplication, it is sometimes possible to remedy the + situation using floating-point operations or SIMD operations such as MMX + (x86) (x86), SSE (x86), VMX (PowerPC), VIS (Sparc). + +

    Using floating-point operations is interesting but somewhat tricky. + Since IEEE double has 53 bit of mantissa, one has to split the operands + in small pieces, so that no intermediates are greater than 2^53. For + 32-bit computers, splitting one operand into 16-bit pieces works. For + 64-bit machines, one operand can be split into 21-bit pieces and the + other into 32-bit pieces. (A 64-bit operand can be split into just three + 21-bit pieces if one allows the split operands to be negative!) + + +

  • Faster sqrt + +

    The current code uses divisions, which are reasonably fast, but it'd be + possible to use only multiplications by computing 1/sqrt(A) using this + iteration: + 

    +				    2
+		   x   = x  (3 − A x )/2
+		    i+1	  i	    i
    + The square root can then be computed like this: + 
    +		     sqrt(A) = A x
+				  n
    +

    That final multiply might be the full size of the input (though it might + only need the high half of that), so there may or may not be any speedup + overall. + +

    We should probably allow a special exponent-like parameter, to speed + computations of a precise square root of a small number in mpf and mpfr. + + +

  • Nth root + +

    Improve mpn_rootrem. The current code is not too bad, but its time + complexity is a function of the input, while it is possible to make + the average complexity a function of the output. + + +

  • Fat binaries + +

    Add more functions to the set of fat functions. + +

    The speed of multiplication is today highly dependent on combination + functions like addlsh1_n. A fat binary will never use any such + functions, since they are classified as optional. Ideally, we should use + them, but making the current compile-time selections of optional functions + become run-time selections for fat binaries. + +

    If we make fat binaries work really well, we should move away frm tehe + current configure scheme (at least by default) and instead include all code + always. + + +

  • Exceptions + +

    Some sort of scheme for exceptions handling would be desirable. + Presently the only thing documented is that divide by zero in GMP + functions provokes a deliberate machine divide by zero (on those systems + where such a thing exists at least). The global gmp_errno + is not actually documented, except for the old gmp_randinit + function. Being currently just a plain global means it's not + thread-safe. + +

    The basic choices for exceptions are returning an error code or having a + handler function to be called. The disadvantage of error returns is they + have to be checked, leading to tedious and rarely executed code, and + strictly speaking such a scheme wouldn't be source or binary compatible. + The disadvantage of a handler function is that a longjmp or + similar recovery from it may be difficult. A combination would be + possible, for instance by allowing the handler to return an error code. + +

    Divide-by-zero, sqrt-of-negative, and similar operand range errors can + normally be detected at the start of functions, so exception handling + would have a clean state. What's worth considering though is that the + GMP function detecting the exception may have been called via some third + party library or self contained application module, and hence have + various bits of state to be cleaned up above it. It'd be highly + desirable for an exceptions scheme to allow for such cleanups. + +

    The C++ destructor mechanism could help with cleanups both internally and + externally, but being a plain C library we don't want to depend on that. + +

    A C++ throw might be a good optional extra exceptions + mechanism, perhaps under a build option. For + GCC -fexceptions will add the necessary frame information to + plain C code, or GMP could be compiled as C++. + +

    Out-of-memory exceptions are expected to be handled by the + mp_set_memory_functions routines, rather than being a + prospective part of divide-by-zero etc. Some similar considerations + apply but what differs is that out-of-memory can arise deep within GMP + internals. Even fundamental routines like mpn_add_n and + mpn_addmul_1 can use temporary memory (for instance on Cray + vector systems). Allowing for an error code return would require an + awful lot of checking internally. Perhaps it'd still be worthwhile, but + it'd be a lot of changes and the extra code would probably be rather + rarely executed in normal usages. + +

    A longjmp recovery for out-of-memory will currently, in + general, lead to memory leaks and may leave GMP variables operated on in + inconsistent states. Maybe it'd be possible to record recovery + information for use by the relevant allocate or reallocate function, but + that too would be a lot of changes. + +

    One scheme for out-of-memory would be to note that all GMP allocations go + through the mp_set_memory_functions routines. So if the + application has an intended setjmp recovery point it can + record memory activity by GMP and abandon space allocated and variables + initialized after that point. This might be as simple as directing the + allocation functions to a separate pool, but in general would have the + disadvantage of needing application-level bookkeeping on top of the + normal system malloc. An advantage however is that it needs + nothing from GMP itself and on that basis doesn't burden applications not + needing recovery. Note that there's probably some details to be worked + out here about reallocs of existing variables, and perhaps about copying + or swapping between "permanent" and "temporary" variables. + +

    Applications desiring a fine-grained error control, for instance a + language interpreter, would very possibly not be well served by a scheme + requiring longjmp. Wrapping every GMP function call with a + setjmp would be very inconvenient. + +

    Another option would be to let mpz_t etc hold a sort of NaN, + a special value indicating an out-of-memory or other failure. This would + be similar to NaNs in mpfr. Unfortunately such a scheme could only be + used by programs prepared to handle such special values, since for + instance a program waiting for some condition to be satisfied could + become an infinite loop if it wasn't also watching for NaNs. The work to + implement this would be significant too, lots of checking of inputs and + intermediate results. And if mpn routines were to + participate in this (which they would have to internally) a lot of new + return values would need to be added, since of course there's no + mpz_t etc structure for them to indicate failure in. + +

    Stack overflow is another possible exception, but perhaps not one that + can be easily detected in general. On i386 GNU/Linux for instance GCC + normally doesn't generate stack probes for an alloca, but + merely adjusts %esp. A big enough alloca can + miss the stack redzone and hit arbitrary data. GMP stack usage is + normally a function of operand size, which might be enough for some + applications to know they'll be safe. Otherwise a fixed maximum usage + can probably be obtained by building with + --enable-alloca=malloc-reentrant (or + notreentrant). Arranging the default to be + alloca only on blocks up to a certain size and + malloc thereafter might be a better approach and would have + the advantage of not having calculations limited by available stack. + +

    Actually recovering from stack overflow is of course another problem. It + might be possible to catch a SIGSEGV in the stack redzone + and do something in a sigaltstack, on systems which have + that, but recovery might otherwise not be possible. This is worth + bearing in mind because there's no point worrying about tight and careful + out-of-memory recovery if an out-of-stack is fatal. + +

    Operand overflow is another exception to be addressed. It's easy for + instance to ask mpz_pow_ui for a result bigger than an + mpz_t can possibly represent. Currently overflows in limb + or byte count calculations will go undetected. Often they'll still end + up asking the memory functions for blocks bigger than available memory, + but that's by no means certain and results are unpredictable in general. + It'd be desirable to tighten up such size calculations. Probably only + selected routines would need checks, if it's assumed say that no input + will be more than half of all memory and hence size additions like say + mpz_mul won't overflow. + + +

  • Performance Tool + +

    It'd be nice to have some sort of tool for getting an overview of + performance. Clearly a great many things could be done, but some primary + uses would be, + +

      +
    1. Checking speed variations between compilers. +
    2. Checking relative performance between systems or CPUs. +
    + +

    A combination of measuring some fundamental routines and some + representative application routines might satisfy these. + +

    The tune/time.c routines would be the easiest way to get good accurate + measurements on lots of different systems. The high level + speed_measure may or may not suit, but the basic + speed_starttime and speed_endtime would cover + lots of portability and accuracy questions. + + +

  • Using restrict + +

    There might be some value in judicious use of C99 style + restrict on various pointers, but this would need some + careful thought about what it implies for the various operand overlaps + permitted in GMP. + +

    Rumour has it some pre-C99 compilers had restrict, but + expressing tighter (or perhaps looser) requirements. Might be worth + investigating that before using restrict unconditionally. + +

    Loops are presumably where the greatest benefit would be had, by allowing + the compiler to advance reads ahead of writes, perhaps as part of loop + unrolling. However critical loops are generally coded in assembler, so + there might not be very much to gain. And on Cray systems the explicit + use of _Pragma gives an equivalent effect. + +

    One thing to note is that Microsoft C headers (on ia64 at least) contain + __declspec(restrict), so a #define of + restrict should be avoided. It might be wisest to setup a + gmp_restrict. + + +

  • Prime Testing + +

    GMP is not really a number theory library and probably shouldn't have + large amounts of code dedicated to sophisticated prime testing + algorithms, but basic things well-implemented would suit. Tests offering + certainty are probably all too big or too slow (or both!) to justify + inclusion in the main library. Demo programs showing some possibilities + would be good though. + +

    The present "repetitions" argument to mpz_probab_prime_p is + rather specific to the Miller-Rabin tests of the current implementation. + Better would be some sort of parameter asking perhaps for a maximum + chance 1/2^x of a probable prime in fact being composite. If + applications follow the advice that the present reps gives 1/4^reps + chance then perhaps such a change is unnecessary, but an explicitly + described 1/2^x would allow for changes in the implementation or even for + new proofs about the theory. + +

    mpz_probab_prime_p always initializes a new + gmp_randstate_t for randomized tests, which unfortunately + means it's not really very random and in particular always runs the same + tests for a given input. Perhaps a new interface could accept an rstate + to use, so successive tests could increase confidence in the result. + +

    mpn_mod_34lsub1 is an obvious and easy improvement to the + trial divisions. And since the various prime factors are constants, the + remainder can be tested with something like +

    +#define MP_LIMB_DIVISIBLE_7_P(n) \
+  ((n) * MODLIMB_INVERSE_7 <= MP_LIMB_T_MAX/7)
+
    + Which would help compilers that don't know how to optimize divisions by + constants, and is even an improvement on current gcc 3.2 code. This + technique works for any modulus, see Granlund and Montgomery "Division by + Invariant Integers" section 9. + +

    The trial divisions are done with primes generated and grouped at + runtime. This could instead be a table of data, with pre-calculated + inverses too. Storing deltas, ie. amounts to add, rather than actual + primes would save space. udiv_qrnnd_preinv style inverses + can be made to exist by adding dummy factors of 2 if necessary. Some + thought needs to be given as to how big such a table should be, based on + how much dividing would be profitable for what sort of size inputs. The + data could be shared by the perfect power testing. + +

    Jason Moxham points out that if a sqrt(-1) mod N exists then any factor + of N must be == 1 mod 4, saving half the work in trial dividing. (If + x^2==-1 mod N then for a prime factor p we have x^2==-1 mod p and so the + jacobi symbol (-1/p)=1. But also (-1/p)=(-1)^((p-1)/2), hence must have + p==1 mod 4.) But knowing whether sqrt(-1) mod N exists is not too easy. + A strong pseudoprime test can reveal one, so perhaps such a test could be + inserted part way though the dividing. + +

    Jon Grantham "Frobenius Pseudoprimes" (www.pseudoprime.com) describes a + quadratic pseudoprime test taking about 3x longer than a plain test, but + with only a 1/7710 chance of error (whereas 3 plain Miller-Rabin tests + would offer only (1/4)^3 == 1/64). Such a test needs completely random + parameters to satisfy the theory, though single-limb values would run + faster. It's probably best to do at least one plain Miller-Rabin before + any quadratic tests, since that can identify composites in less total + time. + +

    Some thought needs to be given to the structure of which tests (trial + division, Miller-Rabin, quadratic) and how many are done, based on what + sort of inputs we expect, with a view to minimizing average time. + +

    It might be a good idea to break out subroutines for the various tests, + so that an application can combine them in ways it prefers, if sensible + defaults in mpz_probab_prime_p don't suit. In particular + this would let applications skip tests it knew would be unprofitable, + like trial dividing when an input is already known to have no small + factors. + +

    For small inputs, combinations of theory and explicit search make it + relatively easy to offer certainty. For instance numbers up to 2^32 + could be handled with a strong pseudoprime test and table lookup. But + it's rather doubtful whether a smallnum prime test belongs in a bignum + library. Perhaps if it had other internal uses. + +

    An mpz_nthprime might be cute, but is almost certainly + impractical for anything but small n. + + +

  • Intra-Library Calls + +

    On various systems, calls within libgmp still go through the PLT, TOC or + other mechanism, which makes the code bigger and slower than it needs to + be. + +

    The theory would be to have all GMP intra-library calls resolved directly + to the routines in the library. An application wouldn't be able to + replace a routine, the way it can normally, but there seems no good + reason to do that, in normal circumstances. + +

    The visibility attribute in recent gcc is good for this, + because it lets gcc omit unnecessary GOT pointer setups or whatever if it + finds all calls are local and there's no global data references. + Documented entrypoints would be protected, and purely + internal things not wanted by test programs or anything can be + internal. + +

    Unfortunately, on i386 it seems protected ends up causing + text segment relocations within libgmp.so, meaning the library code can't + be shared between processes, defeating the purpose of a shared library. + Perhaps this is just a gremlin in binutils (debian packaged + 2.13.90.0.16-1). + +

    The linker can be told directly (with a link script, or options) to do + the same sort of thing. This doesn't change the code emitted by gcc of + course, but it does mean calls are resolved directly to their targets, + avoiding a PLT entry. + +

    Keeping symbols private to libgmp.so is probably a good thing in general + too, to stop anyone even attempting to access them. But some + undocumented things will need or want to be kept visible, for use by + mpfr, or the test and tune programs. Libtool has a standard option for + selecting public symbols (used now for libmp). + + +

  • Math functions for the mpf layer + +

    Implement the functions of math.h for the GMP mpf layer! Check the book + "Pi and the AGM" by Borwein and Borwein for ideas how to do this. These + functions are desirable: acos, acosh, asin, asinh, atan, atanh, atan2, + cos, cosh, exp, log, log10, pow, sin, sinh, tan, tanh. + +

    Note that the mpfr functions already + provide these functions, and that we usually recommend new programs to use + mpfr instead of mpf. +

+
+ + + + + diff --git a/gmp-6.3.0/doc/stamp-vti b/gmp-6.3.0/doc/stamp-vti new file mode 100644 index 0000000..6c23458 --- /dev/null +++ b/gmp-6.3.0/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 29 July 2023 +@set UPDATED-MONTH July 2023 +@set EDITION 6.3.0 +@set VERSION 6.3.0 diff --git a/gmp-6.3.0/doc/tasks.html b/gmp-6.3.0/doc/tasks.html new file mode 100644 index 0000000..9a25bef --- /dev/null +++ b/gmp-6.3.0/doc/tasks.html @@ -0,0 +1,896 @@ + + + + GMP Itemized Development Tasks + + + + + +
+

+ GMP Itemized Development Tasks +

+
+ + +
+Copyright 2000-2004, 2006, 2008, 2009 Free Software Foundation, Inc.
+
+This file is part of the GNU MP Library.
+
+The GNU MP Library is free software; you can redistribute it and/or modify
+it under the terms of either:
+
+  * the GNU Lesser General Public License as published by the Free
+    Software Foundation; either version 3 of the License, or (at your
+    option) any later version.
+
+or
+
+  * the GNU General Public License as published by the Free Software
+    Foundation; either version 2 of the License, or (at your option) any
+    later version.
+
+or both in parallel, as here.
+
+The GNU MP Library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received copies of the GNU General Public License and the
+GNU Lesser General Public License along with the GNU MP Library.  If not,
+see https://www.gnu.org/licenses/.
+
+ + +
+ + This file current as of 29 Jan 2014. An up-to-date version is available at + https://gmplib.org/tasks.html. + Please send comments about this page to gmp-devel@gmplib.org. + +

These are itemized GMP development tasks. Not all the tasks + listed here are suitable for volunteers, but many of them are. + Please see the projects file for more + sizeable projects. + +

CAUTION: This file needs updating. Many of the tasks here have +either already been taken care of, or have become irrelevant. + +

Correctness and Completeness

+
    +
  • _LONG_LONG_LIMB in gmp.h is not namespace clean. Reported + by Patrick Pelissier. +
    + We sort of mentioned _LONG_LONG_LIMB in past releases, so + need to be careful about changing it. It used to be a define + applications had to set for long long limb systems, but that in + particular is no longer relevant now that it's established automatically. +
  • The various reuse.c tests need to force reallocation by calling + _mpz_realloc with a small (1 limb) size. +
  • One reuse case is missing from mpX/tests/reuse.c: + mpz_XXX(a,a,a). +
  • Make the string reading functions allow the `0x' prefix when the base is + explicitly 16. They currently only allow that prefix when the base is + unspecified (zero). +
  • mpf_eq is not always correct, when one operand is + 1000000000... and the other operand is 0111111111..., i.e., extremely + close. There is a special case in mpf_sub for this + situation; put similar code in mpf_eq. [In progress.] +
  • mpf_eq doesn't implement what gmp.texi specifies. It should + not use just whole limbs, but partial limbs. [In progress.] +
  • mpf_set_str doesn't validate it's exponent, for instance + garbage 123.456eX789X is accepted (and an exponent 0 used), and overflow + of a long is not detected. +
  • mpf_add doesn't check for a carry from truncated portions of + the inputs, and in that respect doesn't implement the "infinite precision + followed by truncate" specified in the manual. +
  • Windows DLLs: tests/mpz/reuse.c and tests/mpf/reuse.c initialize global + variables with pointers to mpz_add etc, which doesn't work + when those routines are coming from a DLL (because they're effectively + function pointer global variables themselves). Need to rearrange perhaps + to a set of calls to a test function rather than iterating over an array. +
  • mpz_pow_ui: Detect when the result would be more memory than + a size_t can represent and raise some suitable exception, + probably an alloc call asking for SIZE_T_MAX, and if that + somehow succeeds then an abort. Various size overflows of + this kind are not handled gracefully, probably resulting in segvs. +
    + In mpz_n_pow_ui, detect when the count of low zero bits + exceeds an unsigned long. There's a (small) chance of this + happening but still having enough memory to represent the value. + Reported by Winfried Dreckmann in for instance mpz_ui_pow_ui (x, + 4UL, 1431655766UL). +
  • mpf: Detect exponent overflow and raise some exception. + It'd be nice to allow the full mp_exp_t range since that's + how it's been in the past, but maybe dropping one bit would make it + easier to test if e1+e2 goes out of bounds. +
+ + + +

Machine Independent Optimization

+
    +
  • mpf_cmp: For better cache locality, don't test for low zero + limbs until the high limbs fail to give an ordering. Reduce code size by + turning the three mpn_cmp's into a single loop stopping when + the end of one operand is reached (and then looking for a non-zero in the + rest of the other). +
  • mpf_mul_2exp, mpf_div_2exp: The use of + mpn_lshift for any size<=prec means repeated + mul_2exp and div_2exp calls accumulate low zero + limbs until size==prec+1 is reached. Those zeros will slow down + subsequent operations, especially if the value is otherwise only small. + If low bits of the low limb are zero, use mpn_rshift so as + to not increase the size. +
  • mpn_dc_sqrtrem, mpn_sqrtrem2: Don't use + mpn_add_1 and mpn_sub_1 for 1 limb operations, + instead ADDC_LIMB and SUBC_LIMB. +
  • mpn_sqrtrem2: Use plain variables for sp[0] and + rp[0] calculations, so the compiler needn't worry about + aliasing between sp and rp. +
  • mpn_sqrtrem: Some work can be saved in the last step when + the remainder is not required, as noted in Paul's paper. +
  • mpq_add, mpq_sub: The gcd fits a single limb + with high probability and in this case binvert_limb could + be used to calculate the inverse just once for the two exact divisions + "op1.den / gcd" and "op2.den / gcd", rather than letting + mpn_bdiv_q_1 do it each time. This would require calling + mpn_pi1_bdiv_q_1. +
  • mpn_gcdext: Don't test count_leading_zeros for + zero, instead check the high bit of the operand and avoid invoking + count_leading_zeros. This is an optimization on all + machines, and significant on machines with slow + count_leading_zeros, though it's possible an already + normalized operand might not be encountered very often. +
  • Rewrite umul_ppmm to use floating-point for generating the + most significant limb (if GMP_LIMB_BITS <= 52 bits). + (Peter Montgomery has some ideas on this subject.) +
  • Improve the default umul_ppmm code in longlong.h: Add partial + products with fewer operations. +
  • Consider inlining mpz_set_ui. This would be both small and + fast, especially for compile-time constants, but would make application + binaries depend on having 1 limb allocated to an mpz_t, + preventing the "lazy" allocation scheme below. +
  • Consider inlining mpz_[cft]div_ui and maybe + mpz_[cft]div_r_ui. A __gmp_divide_by_zero + would be needed for the divide by zero test, unless that could be left to + mpn_mod_1 (not sure currently whether all the risc chips + provoke the right exception there if using mul-by-inverse). +
  • Consider inlining: mpz_fits_s*_p. The setups for + LONG_MAX etc would need to go into gmp.h, and on Cray it + might, unfortunately, be necessary to forcibly include <limits.h> + since there's no apparent way to get SHRT_MAX with an + expression (since short and unsigned short can + be different sizes). +
  • mpz_powm and mpz_powm_ui aren't very fast on one + or two limb moduli, due to a lot of function call overheads. These could + perhaps be handled as special cases. +
  • Make sure mpz_powm_ui is never slower than the corresponding + computation using mpz_powm. +
  • mpz_powm REDC should do multiplications by g[] + using the division method when they're small, since the REDC form of a + small multiplier is normally a full size product. Probably would need a + new tuned parameter to say what size multiplier is "small", as a function + of the size of the modulus. +
  • mpn_gcd might be able to be sped up on small to moderate + sizes by improving find_a, possibly just by providing an + alternate implementation for CPUs with slowish + count_leading_zeros. +
  • mpf_set_str produces low zero limbs when a string has a + fraction but is exactly representable, eg. 0.5 in decimal. These could be + stripped to save work in later operations. +
  • mpz_and, mpz_ior and mpz_xor should + use mpn_and_n etc for the benefit of the small number of + targets with native versions of those routines. Need to be careful not to + pass size==0. Is some code sharing possible between the mpz + routines? +
  • mpf_add: Don't do a copy to avoid overlapping operands + unless it's really necessary (currently only sizes are tested, not + whether r really is u or v). +
  • mpf_add: Under the check for v having no effect on the + result, perhaps test for r==u and do nothing in that case, rather than + currently it looks like an MPN_COPY_INCR will be done to + reduce prec+1 limbs to prec. +
  • mpf_div_ui: Instead of padding with low zeros, call + mpn_divrem_1 asking for fractional quotient limbs. +
  • mpf_div_ui: Eliminate TMP_ALLOC. When r!=u + there's no overlap and the division can be called on those operands. + When r==u and is prec+1 limbs, then it's an in-place division. If r==u + and not prec+1 limbs, then move the available limbs up to prec+1 and do + an in-place there. +
  • mpf_div_ui: Whether the high quotient limb is zero can be + determined by testing the dividend for high<divisor. When non-zero, the + division can be done on prec dividend limbs instead of prec+1. The result + size is also known before the division, so that can be a tail call (once + the TMP_ALLOC is eliminated). +
  • mpn_divrem_2 could usefully accept unnormalized divisors and + shift the dividend on-the-fly, since this should cost nothing on + superscalar processors and avoid the need for temporary copying in + mpn_tdiv_qr. +
  • mpf_sqrt: If r!=u, and if u doesn't need to be padded with + zeros, then there's no need for the tp temporary. +
  • mpq_cmp_ui could form the num1*den2 and + num2*den1 products limb-by-limb from high to low and look at + each step for values differing by more than the possible carry bit from + the uncalculated portion. +
  • mpq_cmp could do the same high-to-low progressive multiply + and compare. The benefits of karatsuba and higher multiplication + algorithms are lost, but if it's assumed only a few high limbs will be + needed to determine an order then that's fine. +
  • mpn_add_1, mpn_sub_1, mpn_add, + mpn_sub: Internally use __GMPN_ADD_1 etc + instead of the functions, so they get inlined on all compilers, not just + gcc and others with inline recognised in gmp.h. + __GMPN_ADD_1 etc are meant mostly to support application + inline mpn_add_1 etc and if they don't come out good for + internal uses then special forms can be introduced, for instance many + internal uses are in-place. Sometimes a block of code is executed based + on the carry-out, rather than using it arithmetically, and those places + might want to do their own loops entirely. +
  • __gmp_extract_double on 64-bit systems could use just one + bitfield for the mantissa extraction, not two, when endianness permits. + Might depend on the compiler allowing long long bit fields + when that's the only actual 64-bit type. +
  • tal-notreent.c could keep a block of memory permanently allocated. + Currently the last nested TMP_FREE releases all memory, so + there's an allocate and free every time a top-level function using + TMP is called. Would need + mp_set_memory_functions to tell tal-notreent.c to release + any cached memory when changing allocation functions though. +
  • __gmp_tmp_alloc from tal-notreent.c could be partially + inlined. If the current chunk has enough room then a couple of pointers + can be updated. Only if more space is required then a call to some sort + of __gmp_tmp_increase would be needed. The requirement that + TMP_ALLOC is an expression might make the implementation a + bit ugly and/or a bit sub-optimal. +
    +#define TMP_ALLOC(n)
+  ((ROUND_UP(n) > current->end - current->point ?
+     __gmp_tmp_increase (ROUND_UP (n)) : 0),
+     current->point += ROUND_UP (n),
+     current->point - ROUND_UP (n))
+
    +
  • __mp_bases has a lot of data for bases which are pretty much + never used. Perhaps the table should just go up to base 16, and have + code to generate data above that, if and when required. Naturally this + assumes the code would be smaller than the data saved. +
  • __mp_bases field big_base_inverted is only used + if USE_PREINV_DIVREM_1 is true, and could be omitted + otherwise, to save space. +
  • mpz_get_str, mtox: For power-of-2 bases, which + are of course fast, it seems a little silly to make a second pass over + the mpn_get_str output to convert to ASCII. Perhaps combine + that with the bit extractions. +
  • mpz_gcdext: If the caller requests only the S cofactor (of + A), and A<B, then the code ends up generating the cofactor T (of B) and + deriving S from that. Perhaps it'd be possible to arrange to get S in + the first place by calling mpn_gcdext with A+B,B. This + might only be an advantage if A and B are about the same size. +
  • mpz_n_pow_ui does a good job with small bases and stripping + powers of 2, but it's perhaps a bit too complicated for what it gains. + The simpler mpn_pow_1 is a little faster on small exponents. + (Note some of the ugliness in mpz_n_pow_ui is due to + supporting mpn_mul_2.) +
    + Perhaps the stripping of 2s in mpz_n_pow_ui should be + confined to single limb operands for simplicity and since that's where + the greatest gain would be. +
    + Ideally mpn_pow_1 and mpz_n_pow_ui would be + merged. The reason mpz_n_pow_ui writes to an + mpz_t is that its callers leave it to make a good estimate + of the result size. Callers of mpn_pow_1 already know the + size by separate means (mp_bases). +
  • mpz_invert should call mpn_gcdext directly. +
+ + +

Machine Dependent Optimization

+
    +
  • invert_limb on various processors might benefit from the + little Newton iteration done for alpha and ia64. +
  • Alpha 21264: mpn_addlsh1_n could be implemented with + mpn_addmul_1, since that code at 3.5 is a touch faster than + a separate lshift and add_n at + 1.75+2.125=3.875. Or very likely some specific addlsh1_n + code could beat both. +
  • Alpha 21264: Improve feed-in code for mpn_mul_1, + mpn_addmul_1, and mpn_submul_1. +
  • Alpha 21164: Rewrite mpn_mul_1, mpn_addmul_1, + and mpn_submul_1 for the 21164. This should use both integer + multiplies and floating-point multiplies. For the floating-point + operations, the single-limb multiplier should be split into three 21-bit + chunks, or perhaps even better in four 16-bit chunks. Probably possible + to reach 9 cycles/limb. +
  • Alpha: GCC 3.4 will introduce __builtin_ctzl, + __builtin_clzl and __builtin_popcountl using + the corresponding CIX ct instructions, and + __builtin_alpha_cmpbge. These should give GCC more + information about scheduling etc than the asm blocks + currently used in longlong.h and gmp-impl.h. +
  • Alpha Unicos: Apparently there's no alloca on this system, + making configure choose the slower + malloc-reentrant allocation method. Is there a better way? + Maybe variable-length arrays per notes below. +
  • Alpha Unicos 21164, 21264: .align is not used since it pads + with garbage. Does the code get the intended slotting required for the + claimed speeds? .align at the start of a function would + presumably be safe no matter how it pads. +
  • ARM V5: count_leading_zeros can use the clz + instruction. For GCC 3.4 and up, do this via __builtin_clzl + since then gcc knows it's "predicable". +
  • Itanium: GCC 3.4 introduces __builtin_popcount which can be + used instead of an asm block. The builtin should give gcc + more opportunities for scheduling, bundling and predication. + __builtin_ctz similarly (it just uses popcount as per + current longlong.h). +
  • UltraSPARC/64: Optimize mpn_mul_1, mpn_addmul_1, + for s2 < 2^32 (or perhaps for any zero 16-bit s2 chunk). Not sure how + much this can improve the speed, though, since the symmetry that we rely + on is lost. Perhaps we can just gain cycles when s2 < 2^16, or more + accurately, when two 16-bit s2 chunks which are 16 bits apart are zero. +
  • UltraSPARC/64: Write native mpn_submul_1, analogous to + mpn_addmul_1. +
  • UltraSPARC/64: Write umul_ppmm. Using four + "mulx"s either with an asm block or via the generic C code is + about 90 cycles. Try using fp operations, and also try using karatsuba + for just three "mulx"s. +
  • UltraSPARC/32: Rewrite mpn_lshift, mpn_rshift. + Will give 2 cycles/limb. Trivial modifications of mpn/sparc64 should do. +
  • UltraSPARC/32: Write special mpn_Xmul_1 loops for s2 < 2^16. +
  • UltraSPARC/32: Use mulx for umul_ppmm if + possible (see commented out code in longlong.h). This is unlikely to + save more than a couple of cycles, so perhaps isn't worth bothering with. +
  • UltraSPARC/32: On Solaris gcc doesn't give us __sparc_v9__ + or anything to indicate V9 support when -mcpu=v9 is selected. See + gcc/config/sol2-sld-64.h. Will need to pass something through from + ./configure to select the right code in longlong.h. (Currently nothing + is lost because mulx for multiplying is commented out.) +
  • UltraSPARC/32: mpn_divexact_1 and + mpn_modexact_1c_odd can use a 64-bit inverse and take + 64-bits at a time from the dividend, as per the 32-bit divisor case in + mpn/sparc64/mode1o.c. This must be done in assembler, since the full + 64-bit registers (%gN) are not available from C. +
  • UltraSPARC/32: mpn_divexact_by3c can work 64-bits at a time + using mulx, in assembler. This would be the same as for + sparc64. +
  • UltraSPARC: binvert_limb might save a few cycles from + masking down to just the useful bits at each point in the calculation, + since mulx speed depends on the highest bit set. Either + explicit masks or small types like short and + int ought to work. +
  • Sparc64 HAL R1 popc: This chip reputedly implements + popc properly (see gcc sparc.md). Would need to recognise + it as sparchalr1 or something in configure / config.sub / + config.guess. popc_limb in gmp-impl.h could use this (per + commented out code). count_trailing_zeros could use it too. +
  • PA64: Improve mpn_addmul_1, mpn_submul_1, and + mpn_mul_1. The current code runs at 11 cycles/limb. It + should be possible to saturate the cache, which will happen at 8 + cycles/limb (7.5 for mpn_mul_1). Write special loops for s2 < 2^32; + it should be possible to make them run at about 5 cycles/limb. +
  • PPC601: See which of the power or powerpc32 code runs better. Currently + the powerpc32 is used, but only because it's the default for + powerpc*. +
  • PPC630: Rewrite mpn_addmul_1, mpn_submul_1, and + mpn_mul_1. Use both integer and floating-point operations, + possibly two floating-point and one integer limb per loop. Split operands + into four 16-bit chunks for fast fp operations. Should easily reach 9 + cycles/limb (using one int + one fp), but perhaps even 7 cycles/limb + (using one int + two fp). +
  • PPC630: mpn_rshift could do the same sort of unrolled loop + as mpn_lshift. Some judicious use of m4 might let the two + share source code, or with a register to control the loop direction + perhaps even share object code. +
  • Implement mpn_mul_basecase and mpn_sqr_basecase + for important machines. Helping the generic sqr_basecase.c with an + mpn_sqr_diagonal might be enough for some of the RISCs. +
  • POWER2/POWER2SC: Schedule mpn_lshift/mpn_rshift. + Will bring time from 1.75 to 1.25 cycles/limb. +
  • X86: Optimize non-MMX mpn_lshift for shifts by 1. (See + Pentium code.) +
  • X86: Good authority has it that in the past an inline rep + movs would upset GCC register allocation for the whole function. + Is this still true in GCC 3? It uses rep movs itself for + __builtin_memcpy. Examine the code for some simple and + complex functions to find out. Inlining rep movs would be + desirable, it'd be both smaller and faster. +
  • Pentium P54: mpn_lshift and mpn_rshift can come + down from 6.0 c/l to 5.5 or 5.375 by paying attention to pairing after + shrdl and shldl, see mpn/x86/pentium/README. +
  • Pentium P55 MMX: mpn_lshift and mpn_rshift + might benefit from some destination prefetching. +
  • PentiumPro: mpn_divrem_1 might be able to use a + mul-by-inverse, hoping for maybe 30 c/l. +
  • K7: mpn_lshift and mpn_rshift might be able to + do something branch-free for unaligned startups, and shaving one insn + from the loop with alternative indexing might save a cycle. +
  • PPC32: Try using fewer registers in the current mpn_lshift. + The pipeline is now extremely deep, perhaps unnecessarily deep. +
  • Fujitsu VPP: Vectorize main functions, perhaps in assembly language. +
  • Fujitsu VPP: Write mpn_mul_basecase and + mpn_sqr_basecase. This should use a "vertical multiplication + method", to avoid carry propagation. splitting one of the operands in + 11-bit chunks. +
  • Pentium: mpn_lshift by 31 should use the special rshift + by 1 code, and vice versa mpn_rshift by 31 should use the + special lshift by 1. This would be best as a jump across to the other + routine, could let both live in lshift.asm and omit rshift.asm on finding + mpn_rshift already provided. +
  • Cray T3E: Experiment with optimization options. In particular, + -hpipeline3 seems promising. We should at least up -O to -O2 or -O3. +
  • Cray: mpn_com and mpn_and_n etc very probably + wants a pragma like MPN_COPY_INCR. +
  • Cray vector systems: mpn_lshift, mpn_rshift, + mpn_popcount and mpn_hamdist are nice and small + and could be inlined to avoid function calls. +
  • Cray: Variable length arrays seem to be faster than the tal-notreent.c + scheme. Not sure why, maybe they merely give the compiler more + information about aliasing (or the lack thereof). Would like to modify + TMP_ALLOC to use them, or introduce a new scheme. Memory + blocks wanted unconditionally are easy enough, those wanted only + sometimes are a problem. Perhaps a special size calculation to ask for a + dummy length 1 when unwanted, or perhaps an inlined subroutine + duplicating code under each conditional. Don't really want to turn + everything into a dog's dinner just because Cray don't offer an + alloca. +
  • Cray: mpn_get_str on power-of-2 bases ought to vectorize. + Does it? bits_per_digit and the inner loop over bits in a + limb might prevent it. Perhaps special cases for binary, octal and hex + would be worthwhile (very possibly for all processors too). +
  • S390: BSWAP_LIMB_FETCH looks like it could be done with + lrvg, as per glibc sysdeps/s390/s390-64/bits/byteswap.h. + This is only for 64-bit mode or something is it, since 32-bit mode has + other code? Also, is it worth using for BSWAP_LIMB too, or + would that mean a store and re-fetch? Presumably that's what comes out + in glibc. +
  • Improve count_leading_zeros for 64-bit machines: + 
    +	   if ((x >> 32) == 0) { x <<= 32; cnt += 32; }
+	   if ((x >> 48) == 0) { x <<= 16; cnt += 16; }
+	   ...
    +
  • IRIX 6 MIPSpro compiler has an __inline which could perhaps + be used in __GMP_EXTERN_INLINE. What would be the right way + to identify suitable versions of that compiler? +
  • IRIX cc is rumoured to have an _int_mult_upper + (in <intrinsics.h> like Cray), but it didn't seem to + exist on some IRIX 6.5 systems tried. If it does actually exist + somewhere it would very likely be an improvement over a function call to + umul.asm. +
  • mpn_get_str final divisions by the base with + udiv_qrnd_unnorm could use some sort of multiply-by-inverse + on suitable machines. This ends up happening for decimal by presenting + the compiler with a run-time constant, but the same for other bases would + be good. Perhaps use could be made of the fact base<256. +
  • mpn_umul_ppmm, mpn_udiv_qrnnd: Return a + structure like div_t to avoid going through memory, in + particular helping RISCs that don't do store-to-load forwarding. Clearly + this is only possible if the ABI returns a structure of two + mp_limb_ts in registers. +
    + On PowerPC, structures are returned in memory on AIX and Darwin. In SVR4 + they're returned in registers, except that draft SVR4 had said memory, so + it'd be prudent to check which is done. We can jam the compiler into the + right mode if we know how, since all this is purely internal to libgmp. + (gcc has an option, though of course gcc doesn't matter since we use + inline asm there.) +
+ +

New Functionality

+
    +
  • Maybe add mpz_crr (Chinese Remainder Reconstruction). +
  • Let `0b' and `0B' mean binary input everywhere. +
  • mpz_init and mpq_init could do lazy allocation. + Set ALLOC(var) to 0 to indicate nothing allocated, and let + _mpz_realloc do the initial alloc. Set + z->_mp_d to a dummy that mpz_get_ui and + similar can unconditionally fetch from. Niels Möller has had a go at + this. +
    + The advantages of the lazy scheme would be: +
      +
    • Initial allocate would be the size required for the first value + stored, rather than getting 1 limb in mpz_init and then + more or less immediately reallocating. +
    • mpz_init would only store magic values in the + mpz_t fields, and could be inlined. +
    • A fixed initializer could even be used by applications, like + mpz_t z = MPZ_INITIALIZER;, which might be convenient + for globals. +
    + The advantages of the current scheme are: +
      +
    • mpz_set_ui and other similar routines needn't check the + size allocated and can just store unconditionally. +
    • mpz_set_ui and perhaps others like + mpz_tdiv_r_ui and a prospective + mpz_set_ull could be inlined. +
    +
  • Add mpf_out_raw and mpf_inp_raw. Make sure + format is portable between 32-bit and 64-bit machines, and between + little-endian and big-endian machines. A format which MPFR can use too + would be good. +
  • mpn_and_n ... mpn_copyd: Perhaps make the mpn + logops and copys available in gmp.h, either as library functions or + inlines, with the availability of library functions instantiated in the + generated gmp.h at build time. +
  • mpz_set_str etc variants taking string lengths rather than + null-terminators. +
  • mpz_andn, mpz_iorn, mpz_nand, + mpz_nior, mpz_xnor might be useful additions, + if they could share code with the current such functions (which should be + possible). +
  • mpz_and_ui etc might be of use sometimes. Suggested by + Niels Möller. +
  • mpf_set_str and mpf_inp_str could usefully + accept 0x, 0b etc when base==0. Perhaps the exponent could default to + decimal in this case, with a further 0x, 0b etc allowed there. + Eg. 0xFFAA@0x5A. A leading "0" for octal would match the integers, but + probably something like "0.123" ought not mean octal. +
  • GMP_LONG_LONG_LIMB or some such could become a documented + feature of gmp.h, so applications could know whether to + printf a limb using %lu or %Lu. +
  • GMP_PRIdMP_LIMB and similar defines following C99 + <inttypes.h> might be of use to applications printing limbs. But + if GMP_LONG_LONG_LIMB or whatever is added then perhaps this + can easily enough be left to applications. +
  • gmp_printf could accept %b for binary output. + It'd be nice if it worked for plain int etc too, not just + mpz_t etc. +
  • gmp_printf in fact could usefully accept an arbitrary base, + for both integer and float conversions. A base either in the format + string or as a parameter with * should be allowed. Maybe + &13b (b for base) or something like that. +
  • gmp_printf could perhaps accept mpq_t for float + conversions, eg. "%.4Qf". This would be merely for + convenience, but still might be useful. Rounding would be the same as + for an mpf_t (ie. currently round-to-nearest, but not + actually documented). Alternately, perhaps a separate + mpq_get_str_point or some such might be more use. Suggested + by Pedro Gimeno. +
  • mpz_rscan0 or mpz_revscan0 or some such + searching towards the low end of an integer might match + mpz_scan0 nicely. Likewise for scan1. + Suggested by Roberto Bagnara. +
  • mpz_bit_subset or some such to test whether one integer is a + bitwise subset of another might be of use. Some sort of return value + indicating whether it's a proper or non-proper subset would be good and + wouldn't cost anything in the implementation. Suggested by Roberto + Bagnara. +
  • mpf_get_ld, mpf_set_ld: Conversions between + mpf_t and long double, suggested by Dan + Christensen. Other long double routines might be desirable + too, but mpf would be a start. +
    + long double is an ANSI-ism, so everything involving it would + need to be suppressed on a K&R compiler. +
    + There'd be some work to be done by configure to recognise + the format in use, MPFR has a start on this. Often long + double is the same as double, which is easy but + pretty pointless. A single float format detector macro could look at + double then long double +
    + Sometimes there's a compiler option for the size of a long + double, eg. xlc on AIX can use either 64-bit or 128-bit. It's + probably simplest to regard this as a compiler compatibility issue, and + leave it to users or sysadmins to ensure application and library code is + built the same. +
  • mpz_sqrt_if_perfect_square: When + mpz_perfect_square_p does its tests it calculates a square + root and then discards it. For some applications it might be useful to + return that root. Suggested by Jason Moxham. +
  • mpz_get_ull, mpz_set_ull, + mpz_get_sll, mpz_get_sll: Conversions for + long long. These would aid interoperability, though a + mixture of GMP and long long would probably not be too + common. Since long long is not always available (it's in + C99 and GCC though), disadvantages of using long long in + libgmp.a would be +
      +
    • Library contents vary according to the build compiler. +
    • gmp.h would need an ugly #ifdef block to decide if the + application compiler could take the long long + prototypes. +
    • Some sort of LIBGMP_HAS_LONGLONG might be wanted to + indicate whether the functions are available. (Applications using + autoconf could probe the library too.) +
    + It'd be possible to defer the need for long long to + application compile time, by having something like + mpz_set_2ui called with two halves of a long + long. Disadvantages of this would be, +
      +
    • Bigger code in the application, though perhaps not if a long + long is normally passed as two halves anyway. +
    • mpz_get_ull would be a rather big inline, or would have + to be two function calls. +
    • mpz_get_sll would be a worse inline, and would put the + treatment of -0x10..00 into applications (see + mpz_get_si correctness above). +
    • Although having libgmp.a independent of the build compiler is nice, + it sort of sacrifices the capabilities of a good compiler to + uniformity with inferior ones. +
    + Plain use of long long is probably the lesser evil, if only + because it makes best use of gcc. In fact perhaps it would suffice to + guarantee long long conversions only when using GCC for both + application and library. That would cover free software, and we can + worry about selected vendor compilers later. +
    + In C++ the situation is probably clearer, we demand fairly recent C++ so + long long should be available always. We'd probably prefer + to have the C and C++ the same in respect of long long + support, but it would be possible to have it unconditionally in gmpxx.h, + by some means or another. +
  • mpz_strtoz parsing the same as strtol. + Suggested by Alexander Kruppa. +
+ + +

Configuration

+ +
    +
  • Alpha ev7, ev79: Add code to config.guess to detect these. Believe ev7 + will be "3-1307" in the current switch, but need to verify that. (On + OSF, current configfsf.guess identifies ev7 using psrinfo, we need to do + it ourselves for other systems.) +
  • Alpha OSF: Libtool (version 1.5) doesn't seem to recognise this system is + "pic always" and ends up running gcc twice with the same options. This + is wasteful, but harmless. Perhaps a newer libtool will be better. +
  • ARM: umul_ppmm in longlong.h always uses umull, + but is that available only for M series chips or some such? Perhaps it + should be configured in some way. +
  • HPPA: config.guess should recognize 7000, 7100, 7200, and 8x00. +
  • HPPA: gcc 3.2 introduces a -mschedule=7200 etc parameter, + which could be driven by an exact hppa cpu type. +
  • Mips: config.guess should say mipsr3000, mipsr4000, mipsr10000, etc. + "hinv -c processor" gives lots of information on Irix. Standard + config.guess appends "el" to indicate endianness, but + AC_C_BIGENDIAN seems the best way to handle that for GMP. +
  • PowerPC: The function descriptor nonsense for AIX is currently driven by + *-*-aix*. It might be more reliable to do some sort of + feature test, examining the compiler output perhaps. It might also be + nice to merge the aix.m4 files into powerpc-defs.m4. +
  • config.m4 is generated only by the configure script, it won't be + regenerated by config.status. Creating it as an AC_OUTPUT + would work, but it might upset "make" to have things like L$ + get into the Makefiles through AC_SUBST. + AC_CONFIG_COMMANDS would be the alternative. With some + careful m4 quoting the changequote calls might not be + needed, which might free up the order in which things had to be output. +
  • Automake: Latest automake has a CCAS, CCASFLAGS + scheme. Though we probably wouldn't be using its assembler support we + could try to use those variables in compatible ways. +
  • GMP_LDFLAGS could probably be done with plain + LDFLAGS already used by automake for all linking. But with + a bit of luck the next libtool will pass pretty much all + CFLAGS through to the compiler when linking, making + GMP_LDFLAGS unnecessary. +
  • mpn/Makeasm.am uses -c and -o together in the + .S and .asm rules, but apparently that isn't completely portable (there's + an autoconf AC_PROG_CC_C_O test for it). So far we've not + had problems, but perhaps the rules could be rewritten to use "foo.s" as + the temporary, or to do a suitable "mv" of the result. The only danger + from using foo.s would be if a compile failed and the temporary foo.s + then looked like the primary source. Hopefully if the + SUFFIXES are ordered to have .S and .asm ahead of .s that + wouldn't happen. Might need to check. +
+ + +

Random Numbers

+
    +
  • _gmp_rand is not particularly fast on the linear + congruential algorithm and could stand various improvements. +
      +
    • Make a second seed area within gmp_randstate_t (or + _mp_algdata rather) to save some copying. +
    • Make a special case for a single limb 2exp modulus, to + avoid mpn_mul calls. Perhaps the same for two limbs. +
    • Inline the lc code, to avoid a function call and + TMP_ALLOC for every chunk. +
    • Perhaps the 2exp and general LC cases should be split, + for clarity (if the general case is retained). +
    +
  • gmp_randstate_t used for parameters perhaps should become + gmp_randstate_ptr the same as other types. +
  • Some of the empirical randomness tests could be included in a "make + check". They ought to work everywhere, for a given seed at least. +
+ + +

C++

+
    +
  • mpz_class(string), etc: Use the C++ global locale to + identify whitespace. +
    + mpf_class(string): Use the C++ global locale decimal point, + rather than the C one. +
    + Consider making these variant mpz_set_str etc forms + available for mpz_t too, not just mpz_class + etc. +
  • mpq_class operator+=: Don't emit an unnecessary + mpq_set(q,q) before mpz_addmul etc. +
  • Put various bits of gmpxx.h into libgmpxx, to avoid excessive inlining. + Candidates for this would be, +
      +
    • mpz_class(const char *), etc: since they're normally + not fast anyway, and we can hide the exception throw. +
    • mpz_class(string), etc: to hide the cstr + needed to get to the C conversion function. +
    • mpz_class string, char* etc constructors: likewise to + hide the throws and conversions. +
    • mpz_class::get_str, etc: to hide the char* + to string conversion and free. Perhaps + mpz_get_str can write directly into a + string, to avoid copying. +
      + Consider making such string returning variants + available for use with plain mpz_t etc too. +
    +
+ +

Miscellaneous

+
    +
  • mpz_gcdext and mpn_gcdext ought to document + what range of values the generated cofactors can take, and preferably + ensure the definition uniquely specifies the cofactors for given inputs. + A basic extended Euclidean algorithm or multi-step variant leads to + |x|<|b| and |y|<|a| or something like that, but there's probably + two solutions under just those restrictions. +
  • demos/factorize.c: use mpz_divisible_ui_p rather than + mpz_tdiv_qr_ui. (Of course dividing multiple primes at a + time would be better still.) +
  • The various test programs use quite a bit of the main + libgmp. This establishes good cross-checks, but it might be + better to use simple reference routines where possible. Where it's not + possible some attention could be paid to the order of the tests, so a + libgmp routine is only used for tests once it seems to be + good. +
  • MUL_FFT_THRESHOLD etc: the FFT thresholds should allow a + return to a previous k at certain sizes. This arises basically due to + the step effect caused by size multiples effectively used for each k. + Looking at a graph makes it fairly clear. +
  • __gmp_doprnt_mpf does a rather unattractive round-to-nearest + on the string returned by mpf_get_str. Perhaps some variant + of mpf_get_str could be made which would better suit. +
+ + +

Aids to Development

+
    +
  • Add ASSERTs at the start of each user-visible mpz/mpq/mpf + function to check the validity of each mp?_t parameter, in + particular to check they've been mp?_inited. This might + catch elementary mistakes in user programs. Care would need to be taken + over MPZ_TMP_INITed variables used internally. If nothing + else then consistency checks like size<=alloc, ptr not + NULL and ptr+size not wrapping around the address space, + would be possible. A more sophisticated scheme could track + _mp_d pointers and ensure only a valid one is used. Such a + scheme probably wouldn't be reentrant, not without some help from the + system. +
  • tune/time.c could try to determine at runtime whether + getrusage and gettimeofday are reliable. + Currently we pretend in configure that the dodgy m68k netbsd 1.4.1 + getrusage doesn't exist. If a test might take a long time + to run then perhaps cache the result in a file somewhere. +
  • tune/time.c could choose the default precision based on the + speed_unittime determined, independent of the method in use. +
  • Cray vector systems: CPU frequency could be determined from + sysconf(_SC_CLK_TCK), since it seems to be clock cycle + based. Is this true for all Cray systems? Would like some documentation + or something to confirm. +
+ + +

Documentation

+
    +
  • mpz_inp_str (etc) doesn't say when it stops reading digits. +
  • mpn_get_str isn't terribly clear about how many digits it + produces. It'd probably be possible to say at most one leading zero, + which is what both it and mpz_get_str currently do. But + want to be careful not to bind ourselves to something that might not suit + another implementation. +
  • va_arg doesn't do the right thing with mpz_t + etc directly, but instead needs a pointer type like MP_INT*. + It'd be good to show how to do this, but we'd either need to document + mpz_ptr and friends, or perhaps fallback on something + slightly nasty with void*. +
+ + +

Bright Ideas

+ +

The following may or may not be feasible, and aren't likely to get done in the +near future, but are at least worth thinking about. + +

    +
  • Reorganize longlong.h so that we can inline the operations even for the + system compiler. When there is no such compiler feature, make calls to + stub functions. Write such stub functions for as many machines as + possible. +
  • longlong.h could declare when it's using, or would like to use, + mpn_umul_ppmm, and the corresponding umul.asm file could be + included in libgmp only in that case, the same as is effectively done for + __clz_tab. Likewise udiv.asm and perhaps cntlz.asm. This + would only be a very small space saving, so perhaps not worth the + complexity. +
  • longlong.h could be built at configure time by concatenating or + #including fragments from each directory in the mpn path. This would + select CPU specific macros the same way as CPU specific assembler code. + Code used would no longer depend on cpp predefines, and the current + nested conditionals could be flattened out. +
  • mpz_get_si returns 0x80000000 for -0x100000000, whereas it's + sort of supposed to return the low 31 (or 63) bits. But this is + undocumented, and perhaps not too important. +
  • mpz_init_set* and mpz_realloc could allocate + say an extra 16 limbs over what's needed, so as to reduce the chance of + having to do a reallocate if the mpz_t grows a bit more. + This could only be an option, since it'd badly bloat memory usage in + applications using many small values. +
  • mpq functions could perhaps check for numerator or + denominator equal to 1, on the assumption that integers or + denominator-only values might be expected to occur reasonably often. +
  • count_trailing_zeros is used on more or less uniformly + distributed numbers in a couple of places. For some CPUs + count_trailing_zeros is slow and it's probably worth handling + the frequently occurring 0 to 2 trailing zeros cases specially. +
  • mpf_t might like to let the exponent be undefined when + size==0, instead of requiring it 0 as now. It should be possible to do + size==0 tests before paying attention to the exponent. The advantage is + not needing to set exp in the various places a zero result can arise, + which avoids some tedium but is otherwise perhaps not too important. + Currently mpz_set_f and mpf_cmp_ui depend on + exp==0, maybe elsewhere too. +
  • __gmp_allocate_func: Could use GCC __attribute__ + ((malloc)) on this, though don't know if it'd do much. GCC 3.0 + allows that attribute on functions, but not function pointers (see info + node "Attribute Syntax"), so would need a new autoconf test. This can + wait until there's a GCC that supports it. +
  • mpz_add_ui contains two __GMPN_COPYs, one from + mpn_add_1 and one from mpn_sub_1. If those two + routines were opened up a bit maybe that code could be shared. When a + copy needs to be done there's no carry to append for the add, and if the + copy is non-empty no high zero for the sub. +
+ + +

Old and Obsolete Stuff

+ +

The following tasks apply to chips or systems that are old and/or obsolete. +It's unlikely anything will be done about them unless anyone is actively using +them. + +

    +
  • Sparc32: The integer based udiv_nfp.asm used to be selected by + configure --nfp but that option is gone now that autoconf is + used. The file could go somewhere suitable in the mpn search if any + chips might benefit from it, though it's possible we don't currently + differentiate enough exact cpu types to do this properly. +
  • VAX D and G format double floats are straightforward and + could perhaps be handled directly in __gmp_extract_double + and maybe in mpn_get_d, rather than falling back on the + generic code. (Both formats are detected by configure.) +
+ + +
+ + + + + diff --git a/gmp-6.3.0/doc/texinfo.tex b/gmp-6.3.0/doc/texinfo.tex new file mode 100644 index 0000000..85f184c --- /dev/null +++ b/gmp-6.3.0/doc/texinfo.tex @@ -0,0 +1,10079 @@ +% texinfo.tex -- TeX macros to handle Texinfo files. +% +% Load plain if necessary, i.e., if running under initex. +\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi +% +\def\texinfoversion{2013-02-01.11} +% +% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, +% 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. +% +% This texinfo.tex file is free software: you can redistribute it and/or +% modify it under the terms of the GNU General Public License as +% published by the Free Software Foundation, either version 3 of the +% License, or (at your option) any later version. +% +% This texinfo.tex file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% As a special exception, when this file is read by TeX when processing +% a Texinfo source document, you may use the result without +% restriction. This Exception is an additional permission under section 7 +% of the GNU General Public License, version 3 ("GPLv3"). +% +% Please try the latest version of texinfo.tex before submitting bug +% reports; you can get the latest version from: +% http://ftp.gnu.org/gnu/texinfo/ (the Texinfo release area), or +% http://ftpmirror.gnu.org/texinfo/ (same, via a mirror), or +% http://www.gnu.org/software/texinfo/ (the Texinfo home page) +% The texinfo.tex in any given distribution could well be out +% of date, so if that's what you're using, please check. +% +% Send bug reports to bug-texinfo@gnu.org. Please include including a +% complete document in each bug report with which we can reproduce the +% problem. Patches are, of course, greatly appreciated. +% +% To process a Texinfo manual with TeX, it's most reliable to use the +% texi2dvi shell script that comes with the distribution. For a simple +% manual foo.texi, however, you can get away with this: +% tex foo.texi +% texindex foo.?? +% tex foo.texi +% tex foo.texi +% dvips foo.dvi -o # or whatever; this makes foo.ps. +% The extra TeX runs get the cross-reference information correct. +% Sometimes one run after texindex suffices, and sometimes you need more +% than two; texi2dvi does it as many times as necessary. +% +% It is possible to adapt texinfo.tex for other languages, to some +% extent. You can get the existing language-specific files from the +% full Texinfo distribution. +% +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. + + +\message{Loading texinfo [version \texinfoversion]:} + +% If in a .fmt file, print the version number +% and turn on active characters that we couldn't do earlier because +% they might have appeared in the input file name. +\everyjob{\message{[Texinfo version \texinfoversion]}% + \catcode`+=\active \catcode`\_=\active} + +\chardef\other=12 + +% We never want plain's \outer definition of \+ in Texinfo. +% For @tex, we can use \tabalign. +\let\+ = \relax + +% Save some plain tex macros whose names we will redefine. +\let\ptexb=\b +\let\ptexbullet=\bullet +\let\ptexc=\c +\let\ptexcomma=\, +\let\ptexdot=\. +\let\ptexdots=\dots +\let\ptexend=\end +\let\ptexequiv=\equiv +\let\ptexexclam=\! +\let\ptexfootnote=\footnote +\let\ptexgtr=> +\let\ptexhat=^ +\let\ptexi=\i +\let\ptexindent=\indent +\let\ptexinsert=\insert +\let\ptexlbrace=\{ +\let\ptexless=< +\let\ptexnewwrite\newwrite +\let\ptexnoindent=\noindent +\let\ptexplus=+ +\let\ptexraggedright=\raggedright +\let\ptexrbrace=\} +\let\ptexslash=\/ +\let\ptexstar=\* +\let\ptext=\t +\let\ptextop=\top +{\catcode`\'=\active \global\let\ptexquoteright'}% active in plain's math mode + +% If this character appears in an error message or help string, it +% starts a new line in the output. +\newlinechar = `^^J + +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\thisisundefined + \let\linenumber = \empty % Pre-3.0. +\else + \def\linenumber{l.\the\inputlineno:\space} +\fi + +% Set up fixed words for English if not already set. +\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi +\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi +\ifx\putworderror\undefined \gdef\putworderror{error}\fi +\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi +\ifx\putwordin\undefined \gdef\putwordin{in}\fi +\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi +\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi +\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi +\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi +\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi +\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi +\ifx\putwordof\undefined \gdef\putwordof{of}\fi +\ifx\putwordon\undefined \gdef\putwordon{on}\fi +\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi +\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi +\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi +\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi +\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi +\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi +\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi +% +\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi +\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi +\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi +\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi +\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi +\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi +\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi +\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi +\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi +\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi +\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi +\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi +% +\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi +\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi +\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi +\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi +\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi + +% Since the category of space is not known, we have to be careful. +\chardef\spacecat = 10 +\def\spaceisspace{\catcode`\ =\spacecat} + +% sometimes characters are active, so we need control sequences. +\chardef\ampChar = `\& +\chardef\colonChar = `\: +\chardef\commaChar = `\, +\chardef\dashChar = `\- +\chardef\dotChar = `\. +\chardef\exclamChar= `\! +\chardef\hashChar = `\# +\chardef\lquoteChar= `\` +\chardef\questChar = `\? +\chardef\rquoteChar= `\' +\chardef\semiChar = `\; +\chardef\slashChar = `\/ +\chardef\underChar = `\_ + +% Ignore a token. +% +\def\gobble#1{} + +% The following is used inside several \edef's. +\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} + +% Hyphenation fixes. +\hyphenation{ + Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script + ap-pen-dix bit-map bit-maps + data-base data-bases eshell fall-ing half-way long-est man-u-script + man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm + par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces + spell-ing spell-ings + stand-alone strong-est time-stamp time-stamps which-ever white-space + wide-spread wrap-around +} + +% Margin to add to right of even pages, to left of odd pages. +\newdimen\bindingoffset +\newdimen\normaloffset +\newdimen\pagewidth \newdimen\pageheight + +% For a final copy, take out the rectangles +% that mark overfull boxes (in case you have decided +% that the text looks ok even though it passes the margin). +% +\def\finalout{\overfullrule=0pt } + +% Sometimes it is convenient to have everything in the transcript file +% and nothing on the terminal. We don't just call \tracingall here, +% since that produces some useless output on the terminal. We also make +% some effort to order the tracing commands to reduce output in the log +% file; cf. trace.sty in LaTeX. +% +\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% +\def\loggingall{% + \tracingstats2 + \tracingpages1 + \tracinglostchars2 % 2 gives us more in etex + \tracingparagraphs1 + \tracingoutput1 + \tracingmacros2 + \tracingrestores1 + \showboxbreadth\maxdimen \showboxdepth\maxdimen + \ifx\eTeXversion\thisisundefined\else % etex gives us more logging + \tracingscantokens1 + \tracingifs1 + \tracinggroups1 + \tracingnesting2 + \tracingassigns1 + \fi + \tracingcommands3 % 3 gives us more in etex + \errorcontextlines16 +}% + +% @errormsg{MSG}. Do the index-like expansions on MSG, but if things +% aren't perfect, it's not the end of the world, being an error message, +% after all. +% +\def\errormsg{\begingroup \indexnofonts \doerrormsg} +\def\doerrormsg#1{\errmessage{#1}} + +% add check for \lastpenalty to plain's definitions. If the last thing +% we did was a \nobreak, we don't want to insert more space. +% +\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount + \removelastskip\penalty-50\smallskip\fi\fi} +\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount + \removelastskip\penalty-100\medskip\fi\fi} +\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount + \removelastskip\penalty-200\bigskip\fi\fi} + +% Do @cropmarks to get crop marks. +% +\newif\ifcropmarks +\let\cropmarks = \cropmarkstrue +% +% Dimensions to add cropmarks at corners. +% Added by P. A. MacKay, 12 Nov. 1986 +% +\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines +\newdimen\cornerlong \cornerlong=1pc +\newdimen\cornerthick \cornerthick=.3pt +\newdimen\topandbottommargin \topandbottommargin=.75in + +% Output a mark which sets \thischapter, \thissection and \thiscolor. +% We dump everything together because we only have one kind of mark. +% This works because we only use \botmark / \topmark, not \firstmark. +% +% A mark contains a subexpression of the \ifcase ... \fi construct. +% \get*marks macros below extract the needed part using \ifcase. +% +% Another complication is to let the user choose whether \thischapter +% (\thissection) refers to the chapter (section) in effect at the top +% of a page, or that at the bottom of a page. The solution is +% described on page 260 of The TeXbook. It involves outputting two +% marks for the sectioning macros, one before the section break, and +% one after. I won't pretend I can describe this better than DEK... +\def\domark{% + \toks0=\expandafter{\lastchapterdefs}% + \toks2=\expandafter{\lastsectiondefs}% + \toks4=\expandafter{\prevchapterdefs}% + \toks6=\expandafter{\prevsectiondefs}% + \toks8=\expandafter{\lastcolordefs}% + \mark{% + \the\toks0 \the\toks2 + \noexpand\or \the\toks4 \the\toks6 + \noexpand\else \the\toks8 + }% +} +% \topmark doesn't work for the very first chapter (after the title +% page or the contents), so we use \firstmark there -- this gets us +% the mark with the chapter defs, unless the user sneaks in, e.g., +% @setcolor (or @url, or @link, etc.) between @contents and the very +% first @chapter. +\def\gettopheadingmarks{% + \ifcase0\topmark\fi + \ifx\thischapter\empty \ifcase0\firstmark\fi \fi +} +\def\getbottomheadingmarks{\ifcase1\botmark\fi} +\def\getcolormarks{\ifcase2\topmark\fi} + +% Avoid "undefined control sequence" errors. +\def\lastchapterdefs{} +\def\lastsectiondefs{} +\def\prevchapterdefs{} +\def\prevsectiondefs{} +\def\lastcolordefs{} + +% Main output routine. +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox +\newbox\footlinebox + +% \onepageout takes a vbox as an argument. Note that \pagecontents +% does insertions, but you have to call it yourself. +\def\onepageout#1{% + \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi + % + \ifodd\pageno \advance\hoffset by \bindingoffset + \else \advance\hoffset by -\bindingoffset\fi + % + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi + \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % + {% + % Have to do this stuff outside the \shipout because we want it to + % take effect in \write's, yet the group defined by the \vbox ends + % before the \shipout runs. + % + \indexdummies % don't expand commands in the output. + \normalturnoffactive % \ in index entries must not stay \, e.g., if + % the page break happens to be in the middle of an example. + % We don't want .vr (or whatever) entries like this: + % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} + % "\acronym" won't work when it's read back in; + % it needs to be + % {\code {{\tt \backslashcurfont }acronym} + \shipout\vbox{% + % Do this early so pdf references go to the beginning of the page. + \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi + % + \ifcropmarks \vbox to \outervsize\bgroup + \hsize = \outerhsize + \vskip-\topandbottommargin + \vtop to0pt{% + \line{\ewtop\hfil\ewtop}% + \nointerlineskip + \line{% + \vbox{\moveleft\cornerthick\nstop}% + \hfill + \vbox{\moveright\cornerthick\nstop}% + }% + \vss}% + \vskip\topandbottommargin + \line\bgroup + \hfil % center the page within the outer (page) hsize. + \ifodd\pageno\hskip\bindingoffset\fi + \vbox\bgroup + \fi + % + \unvbox\headlinebox + \pagebody{#1}% + \ifdim\ht\footlinebox > 0pt + % Only leave this space if the footline is nonempty. + % (We lessened \vsize for it in \oddfootingyyy.) + % The \baselineskip=24pt in plain's \makefootline has no effect. + \vskip 24pt + \unvbox\footlinebox + \fi + % + \ifcropmarks + \egroup % end of \vbox\bgroup + \hfil\egroup % end of (centering) \line\bgroup + \vskip\topandbottommargin plus1fill minus1fill + \boxmaxdepth = \cornerthick + \vbox to0pt{\vss + \line{% + \vbox{\moveleft\cornerthick\nsbot}% + \hfill + \vbox{\moveright\cornerthick\nsbot}% + }% + \nointerlineskip + \line{\ewbot\hfil\ewbot}% + }% + \egroup % \vbox from first cropmarks clause + \fi + }% end of \shipout\vbox + }% end of group with \indexdummies + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi +} + +\newinsert\margin \dimen\margin=\maxdimen + +\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} +{\catcode`\@ =11 +\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi +% marginal hacks, juha@viisa.uucp (Juha Takala) +\ifvoid\margin\else % marginal info is present + \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi +\dimen@=\dp#1\relax \unvbox#1\relax +\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi +\ifr@ggedbottom \kern-\dimen@ \vfil \fi} +} + +% Here are the rules for the cropmarks. Note that they are +% offset so that the space between them is truly \outerhsize or \outervsize +% (P. A. MacKay, 12 November, 1986) +% +\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} +\def\nstop{\vbox + {\hrule height\cornerthick depth\cornerlong width\cornerthick}} +\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} +\def\nsbot{\vbox + {\hrule height\cornerlong depth\cornerthick width\cornerthick}} + +% Parse an argument, then pass it to #1. The argument is the rest of +% the input line (except we remove a trailing comment). #1 should be a +% macro which expects an ordinary undelimited TeX argument. +% +\def\parsearg{\parseargusing{}} +\def\parseargusing#1#2{% + \def\argtorun{#2}% + \begingroup + \obeylines + \spaceisspace + #1% + \parseargline\empty% Insert the \empty token, see \finishparsearg below. +} + +{\obeylines % + \gdef\parseargline#1^^M{% + \endgroup % End of the group started in \parsearg. + \argremovecomment #1\comment\ArgTerm% + }% +} + +% First remove any @comment, then any @c comment. +\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} + +% Each occurrence of `\^^M' or `\^^M' is replaced by a single space. +% +% \argremovec might leave us with trailing space, e.g., +% @end itemize @c foo +% This space token undergoes the same procedure and is eventually removed +% by \finishparsearg. +% +\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} +\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} +\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% + \def\temp{#3}% + \ifx\temp\empty + % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: + \let\temp\finishparsearg + \else + \let\temp\argcheckspaces + \fi + % Put the space token in: + \temp#1 #3\ArgTerm +} + +% If a _delimited_ argument is enclosed in braces, they get stripped; so +% to get _exactly_ the rest of the line, we had to prevent such situation. +% We prepended an \empty token at the very beginning and we expand it now, +% just before passing the control to \argtorun. +% (Similarly, we have to think about #3 of \argcheckspacesY above: it is +% either the null string, or it ends with \^^M---thus there is no danger +% that a pair of braces would be stripped. +% +% But first, we have to remove the trailing space token. +% +\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} + +% \parseargdef\foo{...} +% is roughly equivalent to +% \def\foo{\parsearg\Xfoo} +% \def\Xfoo#1{...} +% +% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my +% favourite TeX trick. --kasal, 16nov03 + +\def\parseargdef#1{% + \expandafter \doparseargdef \csname\string#1\endcsname #1% +} +\def\doparseargdef#1#2{% + \def#2{\parsearg#1}% + \def#1##1% +} + +% Several utility definitions with active space: +{ + \obeyspaces + \gdef\obeyedspace{ } + + % Make each space character in the input produce a normal interword + % space in the output. Don't allow a line break at this space, as this + % is used only in environments like @example, where each line of input + % should produce a line of output anyway. + % + \gdef\sepspaces{\obeyspaces\let =\tie} + + % If an index command is used in an @example environment, any spaces + % therein should become regular spaces in the raw index file, not the + % expansion of \tie (\leavevmode \penalty \@M \ ). + \gdef\unsepspaces{\let =\space} +} + + +\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} + +% Define the framework for environments in texinfo.tex. It's used like this: +% +% \envdef\foo{...} +% \def\Efoo{...} +% +% It's the responsibility of \envdef to insert \begingroup before the +% actual body; @end closes the group after calling \Efoo. \envdef also +% defines \thisenv, so the current environment is known; @end checks +% whether the environment name matches. The \checkenv macro can also be +% used to check whether the current environment is the one expected. +% +% Non-false conditionals (@iftex, @ifset) don't fit into this, so they +% are not treated as environments; they don't open a group. (The +% implementation of @end takes care not to call \endgroup in this +% special case.) + + +% At run-time, environments start with this: +\def\startenvironment#1{\begingroup\def\thisenv{#1}} +% initialize +\let\thisenv\empty + +% ... but they get defined via ``\envdef\foo{...}'': +\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} +\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} + +% Check whether we're in the right environment: +\def\checkenv#1{% + \def\temp{#1}% + \ifx\thisenv\temp + \else + \badenverr + \fi +} + +% Environment mismatch, #1 expected: +\def\badenverr{% + \errhelp = \EMsimple + \errmessage{This command can appear only \inenvironment\temp, + not \inenvironment\thisenv}% +} +\def\inenvironment#1{% + \ifx#1\empty + outside of any environment% + \else + in environment \expandafter\string#1% + \fi +} + +% @end foo executes the definition of \Efoo. +% But first, it executes a specialized version of \checkenv +% +\parseargdef\end{% + \if 1\csname iscond.#1\endcsname + \else + % The general wording of \badenverr may not be ideal. + \expandafter\checkenv\csname#1\endcsname + \csname E#1\endcsname + \endgroup + \fi +} + +\newhelp\EMsimple{Press RETURN to continue.} + + +% Be sure we're in horizontal mode when doing a tie, since we make space +% equivalent to this in @example-like environments. Otherwise, a space +% at the beginning of a line will start with \penalty -- and +% since \penalty is valid in vertical mode, we'd end up putting the +% penalty on the vertical list instead of in the new paragraph. +{\catcode`@ = 11 + % Avoid using \@M directly, because that causes trouble + % if the definition is written into an index file. + \global\let\tiepenalty = \@M + \gdef\tie{\leavevmode\penalty\tiepenalty\ } +} + +% @: forces normal size whitespace following. +\def\:{\spacefactor=1000 } + +% @* forces a line break. +\def\*{\unskip\hfil\break\hbox{}\ignorespaces} + +% @/ allows a line break. +\let\/=\allowbreak + +% @. is an end-of-sentence period. +\def\.{.\spacefactor=\endofsentencespacefactor\space} + +% @! is an end-of-sentence bang. +\def\!{!\spacefactor=\endofsentencespacefactor\space} + +% @? is an end-of-sentence query. +\def\?{?\spacefactor=\endofsentencespacefactor\space} + +% @frenchspacing on|off says whether to put extra space after punctuation. +% +\def\onword{on} +\def\offword{off} +% +\parseargdef\frenchspacing{% + \def\temp{#1}% + \ifx\temp\onword \plainfrenchspacing + \else\ifx\temp\offword \plainnonfrenchspacing + \else + \errhelp = \EMsimple + \errmessage{Unknown @frenchspacing option `\temp', must be on|off}% + \fi\fi +} + +% @w prevents a word break. Without the \leavevmode, @w at the +% beginning of a paragraph, when TeX is still in vertical mode, would +% produce a whole line of output instead of starting the paragraph. +\def\w#1{\leavevmode\hbox{#1}} + +% @group ... @end group forces ... to be all on one page, by enclosing +% it in a TeX vbox. We use \vtop instead of \vbox to construct the box +% to keep its height that of a normal line. According to the rules for +% \topskip (p.114 of the TeXbook), the glue inserted is +% max (\topskip - \ht (first item), 0). If that height is large, +% therefore, no glue is inserted, and the space between the headline and +% the text is small, which looks bad. +% +% Another complication is that the group might be very large. This can +% cause the glue on the previous page to be unduly stretched, because it +% does not have much material. In this case, it's better to add an +% explicit \vfill so that the extra space is at the bottom. The +% threshold for doing this is if the group is more than \vfilllimit +% percent of a page (\vfilllimit can be changed inside of @tex). +% +\newbox\groupbox +\def\vfilllimit{0.7} +% +\envdef\group{% + \ifnum\catcode`\^^M=\active \else + \errhelp = \groupinvalidhelp + \errmessage{@group invalid in context where filling is enabled}% + \fi + \startsavinginserts + % + \setbox\groupbox = \vtop\bgroup + % Do @comment since we are called inside an environment such as + % @example, where each end-of-line in the input causes an + % end-of-line in the output. We don't want the end-of-line after + % the `@group' to put extra space in the output. Since @group + % should appear on a line by itself (according to the Texinfo + % manual), we don't worry about eating any user text. + \comment +} +% +% The \vtop produces a box with normal height and large depth; thus, TeX puts +% \baselineskip glue before it, and (when the next line of text is done) +% \lineskip glue after it. Thus, space below is not quite equal to space +% above. But it's pretty close. +\def\Egroup{% + % To get correct interline space between the last line of the group + % and the first line afterwards, we have to propagate \prevdepth. + \endgraf % Not \par, as it may have been set to \lisppar. + \global\dimen1 = \prevdepth + \egroup % End the \vtop. + % \dimen0 is the vertical size of the group's box. + \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox + % \dimen2 is how much space is left on the page (more or less). + \dimen2 = \pageheight \advance\dimen2 by -\pagetotal + % if the group doesn't fit on the current page, and it's a big big + % group, force a page break. + \ifdim \dimen0 > \dimen2 + \ifdim \pagetotal < \vfilllimit\pageheight + \page + \fi + \fi + \box\groupbox + \prevdepth = \dimen1 + \checkinserts +} +% +% TeX puts in an \escapechar (i.e., `@') at the beginning of the help +% message, so this ends up printing `@group can only ...'. +% +\newhelp\groupinvalidhelp{% +group can only be used in environments such as @example,^^J% +where each line of input produces a line of output.} + +% @need space-in-mils +% forces a page break if there is not space-in-mils remaining. + +\newdimen\mil \mil=0.001in + +\parseargdef\need{% + % Ensure vertical mode, so we don't make a big box in the middle of a + % paragraph. + \par + % + % If the @need value is less than one line space, it's useless. + \dimen0 = #1\mil + \dimen2 = \ht\strutbox + \advance\dimen2 by \dp\strutbox + \ifdim\dimen0 > \dimen2 + % + % Do a \strut just to make the height of this box be normal, so the + % normal leading is inserted relative to the preceding line. + % And a page break here is fine. + \vtop to #1\mil{\strut\vfil}% + % + % TeX does not even consider page breaks if a penalty added to the + % main vertical list is 10000 or more. But in order to see if the + % empty box we just added fits on the page, we must make it consider + % page breaks. On the other hand, we don't want to actually break the + % page after the empty box. So we use a penalty of 9999. + % + % There is an extremely small chance that TeX will actually break the + % page at this \penalty, if there are no other feasible breakpoints in + % sight. (If the user is using lots of big @group commands, which + % almost-but-not-quite fill up a page, TeX will have a hard time doing + % good page breaking, for example.) However, I could not construct an + % example where a page broke at this \penalty; if it happens in a real + % document, then we can reconsider our strategy. + \penalty9999 + % + % Back up by the size of the box, whether we did a page break or not. + \kern -#1\mil + % + % Do not allow a page break right after this kern. + \nobreak + \fi +} + +% @br forces paragraph break (and is undocumented). + +\let\br = \par + +% @page forces the start of a new page. +% +\def\page{\par\vfill\supereject} + +% @exdent text.... +% outputs text on separate line in roman font, starting at standard page margin + +% This records the amount of indent in the innermost environment. +% That's how much \exdent should take out. +\newskip\exdentamount + +% This defn is used inside fill environments such as @defun. +\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} + +% This defn is used inside nofill environments such as @example. +\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount + \leftline{\hskip\leftskip{\rm#1}}}} + +% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current +% paragraph. For more general purposes, use the \margin insertion +% class. WHICH is `l' or `r'. Not documented, written for gawk manual. +% +\newskip\inmarginspacing \inmarginspacing=1cm +\def\strutdepth{\dp\strutbox} +% +\def\doinmargin#1#2{\strut\vadjust{% + \nobreak + \kern-\strutdepth + \vtop to \strutdepth{% + \baselineskip=\strutdepth + \vss + % if you have multiple lines of stuff to put here, you'll need to + % make the vbox yourself of the appropriate size. + \ifx#1l% + \llap{\ignorespaces #2\hskip\inmarginspacing}% + \else + \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% + \fi + \null + }% +}} +\def\inleftmargin{\doinmargin l} +\def\inrightmargin{\doinmargin r} +% +% @inmargin{TEXT [, RIGHT-TEXT]} +% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; +% else use TEXT for both). +% +\def\inmargin#1{\parseinmargin #1,,\finish} +\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \def\lefttext{#1}% have both texts + \def\righttext{#2}% + \else + \def\lefttext{#1}% have only one text + \def\righttext{#1}% + \fi + % + \ifodd\pageno + \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin + \else + \def\temp{\inleftmargin\lefttext}% + \fi + \temp +} + +% @| inserts a changebar to the left of the current line. It should +% surround any changed text. This approach does *not* work if the +% change spans more than two lines of output. To handle that, we would +% have adopt a much more difficult approach (putting marks into the main +% vertical list for the beginning and end of each change). This command +% is not documented, not supported, and doesn't work. +% +\def\|{% + % \vadjust can only be used in horizontal mode. + \leavevmode + % + % Append this vertical mode material after the current line in the output. + \vadjust{% + % We want to insert a rule with the height and depth of the current + % leading; that is exactly what \strutbox is supposed to record. + \vskip-\baselineskip + % + % \vadjust-items are inserted at the left edge of the type. So + % the \llap here moves out into the left-hand margin. + \llap{% + % + % For a thicker or thinner bar, change the `1pt'. + \vrule height\baselineskip width1pt + % + % This is the space between the bar and the text. + \hskip 12pt + }% + }% +} + +% @include FILE -- \input text of FILE. +% +\def\include{\parseargusing\filenamecatcodes\includezzz} +\def\includezzz#1{% + \pushthisfilestack + \def\thisfile{#1}% + {% + \makevalueexpandable % we want to expand any @value in FILE. + \turnoffactive % and allow special characters in the expansion + \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @include of #1^^J}% + \edef\temp{\noexpand\input #1 }% + % + % This trickery is to read FILE outside of a group, in case it makes + % definitions, etc. + \expandafter + }\temp + \popthisfilestack +} +\def\filenamecatcodes{% + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other + \catcode`-=\other + \catcode`\`=\other + \catcode`\'=\other +} + +\def\pushthisfilestack{% + \expandafter\pushthisfilestackX\popthisfilestack\StackTerm +} +\def\pushthisfilestackX{% + \expandafter\pushthisfilestackY\thisfile\StackTerm +} +\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% + \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% +} + +\def\popthisfilestack{\errthisfilestackempty} +\def\errthisfilestackempty{\errmessage{Internal error: + the stack of filenames is empty.}} +% +\def\thisfile{} + +% @center line +% outputs that line, centered. +% +\parseargdef\center{% + \ifhmode + \let\centersub\centerH + \else + \let\centersub\centerV + \fi + \centersub{\hfil \ignorespaces#1\unskip \hfil}% + \let\centersub\relax % don't let the definition persist, just in case +} +\def\centerH#1{{% + \hfil\break + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{#1}% + \break +}} +% +\newcount\centerpenalty +\def\centerV#1{% + % The idea here is the same as in \startdefun, \cartouche, etc.: if + % @center is the first thing after a section heading, we need to wipe + % out the negative parskip inserted by \sectionheading, but still + % prevent a page break here. + \centerpenalty = \lastpenalty + \ifnum\centerpenalty>10000 \vskip\parskip \fi + \ifnum\centerpenalty>9999 \penalty\centerpenalty \fi + \line{\kern\leftskip #1\kern\rightskip}% +} + +% @sp n outputs n lines of vertical space +% +\parseargdef\sp{\vskip #1\baselineskip} + +% @comment ...line which is ignored... +% @c is the same as @comment +% @ignore ... @end ignore is another way to write a comment +% +\def\comment{\begingroup \catcode`\^^M=\other% +\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% +\commentxxx} +{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} +% +\let\c=\comment + +% @paragraphindent NCHARS +% We'll use ems for NCHARS, close enough. +% NCHARS can also be the word `asis' or `none'. +% We cannot feasibly implement @paragraphindent asis, though. +% +\def\asisword{asis} % no translation, these are keywords +\def\noneword{none} +% +\parseargdef\paragraphindent{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \defaultparindent = 0pt + \else + \defaultparindent = #1em + \fi + \fi + \parindent = \defaultparindent +} + +% @exampleindent NCHARS +% We'll use ems for NCHARS like @paragraphindent. +% It seems @exampleindent asis isn't necessary, but +% I preserve it to make it similar to @paragraphindent. +\parseargdef\exampleindent{% + \def\temp{#1}% + \ifx\temp\asisword + \else + \ifx\temp\noneword + \lispnarrowing = 0pt + \else + \lispnarrowing = #1em + \fi + \fi +} + +% @firstparagraphindent WORD +% If WORD is `none', then suppress indentation of the first paragraph +% after a section heading. If WORD is `insert', then do indent at such +% paragraphs. +% +% The paragraph indentation is suppressed or not by calling +% \suppressfirstparagraphindent, which the sectioning commands do. +% We switch the definition of this back and forth according to WORD. +% By default, we suppress indentation. +% +\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} +\def\insertword{insert} +% +\parseargdef\firstparagraphindent{% + \def\temp{#1}% + \ifx\temp\noneword + \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent + \else\ifx\temp\insertword + \let\suppressfirstparagraphindent = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @firstparagraphindent option `\temp'}% + \fi\fi +} + +% Here is how we actually suppress indentation. Redefine \everypar to +% \kern backwards by \parindent, and then reset itself to empty. +% +% We also make \indent itself not actually do anything until the next +% paragraph. +% +\gdef\dosuppressfirstparagraphindent{% + \gdef\indent{% + \restorefirstparagraphindent + \indent + }% + \gdef\noindent{% + \restorefirstparagraphindent + \noindent + }% + \global\everypar = {% + \kern -\parindent + \restorefirstparagraphindent + }% +} + +\gdef\restorefirstparagraphindent{% + \global \let \indent = \ptexindent + \global \let \noindent = \ptexnoindent + \global \everypar = {}% +} + + +% @refill is a no-op. +\let\refill=\relax + +% If working on a large document in chapters, it is convenient to +% be able to disable indexing, cross-referencing, and contents, for test runs. +% This is done with @novalidate (before @setfilename). +% +\newif\iflinks \linkstrue % by default we want the aux files. +\let\novalidate = \linksfalse + +% @setfilename is done at the beginning of every texinfo file. +% So open here the files we need to have open while reading the input. +% This makes it possible to make a .fmt file for texinfo. +\def\setfilename{% + \fixbackslash % Turn off hack to swallow `\input texinfo'. + \iflinks + \tryauxfile + % Open the new aux file. TeX will close it automatically at exit. + \immediate\openout\auxfile=\jobname.aux + \fi % \openindices needs to do some work in any case. + \openindices + \let\setfilename=\comment % Ignore extra @setfilename cmds. + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. + \openin 1 texinfo.cnf + \ifeof 1 \else \input texinfo.cnf \fi + \closein 1 + % + \comment % Ignore the actual filename. +} + +% Called from \setfilename. +% +\def\openindices{% + \newindex{cp}% + \newcodeindex{fn}% + \newcodeindex{vr}% + \newcodeindex{tp}% + \newcodeindex{ky}% + \newcodeindex{pg}% +} + +% @bye. +\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} + + +\message{pdf,} +% adobe `portable' document format +\newcount\tempnum +\newcount\lnkcount +\newtoks\filename +\newcount\filenamelength +\newcount\pgn +\newtoks\toksA +\newtoks\toksB +\newtoks\toksC +\newtoks\toksD +\newbox\boxA +\newcount\countA +\newif\ifpdf +\newif\ifpdfmakepagedest + +% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 +% can be set). So we test for \relax and 0 as well as being undefined. +\ifx\pdfoutput\thisisundefined +\else + \ifx\pdfoutput\relax + \else + \ifcase\pdfoutput + \else + \pdftrue + \fi + \fi +\fi + +% PDF uses PostScript string constants for the names of xref targets, +% for display in the outlines, and in other places. Thus, we have to +% double any backslashes. Otherwise, a name like "\node" will be +% interpreted as a newline (\n), followed by o, d, e. Not good. +% +% See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and +% related messages. The final outcome is that it is up to the TeX user +% to double the backslashes and otherwise make the string valid, so +% that's what we do. pdftex 1.30.0 (ca.2005) introduced a primitive to +% do this reliably, so we use it. + +% #1 is a control sequence in which to do the replacements, +% which we \xdef. +\def\txiescapepdf#1{% + \ifx\pdfescapestring\thisisundefined + % No primitive available; should we give a warning or log? + % Many times it won't matter. + \else + % The expandable \pdfescapestring primitive escapes parentheses, + % backslashes, and other special chars. + \xdef#1{\pdfescapestring{#1}}% + \fi +} + +\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images +with PDF output, and none of those formats could be found. (.eps cannot +be supported due to the design of the PDF format; use regular TeX (DVI +output) for that.)} + +\ifpdf + % + % Color manipulation macros based on pdfcolor.tex, + % except using rgb instead of cmyk; the latter is said to render as a + % very dark gray on-screen and a very dark halftone in print, instead + % of actual black. + \def\rgbDarkRed{0.50 0.09 0.12} + \def\rgbBlack{0 0 0} + % + % k sets the color for filling (usual text, etc.); + % K sets the color for stroking (thin rules, e.g., normal _'s). + \def\pdfsetcolor#1{\pdfliteral{#1 rg #1 RG}} + % + % Set color, and create a mark which defines \thiscolor accordingly, + % so that \makeheadline knows which color to restore. + \def\setcolor#1{% + \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% + \domark + \pdfsetcolor{#1}% + } + % + \def\maincolor{\rgbBlack} + \pdfsetcolor{\maincolor} + \edef\thiscolor{\maincolor} + \def\lastcolordefs{} + % + \def\makefootline{% + \baselineskip24pt + \line{\pdfsetcolor{\maincolor}\the\footline}% + } + % + \def\makeheadline{% + \vbox to 0pt{% + \vskip-22.5pt + \line{% + \vbox to8.5pt{}% + % Extract \thiscolor definition from the marks. + \getcolormarks + % Typeset the headline with \maincolor, then restore the color. + \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}% + }% + \vss + }% + \nointerlineskip + } + % + % + \pdfcatalog{/PageMode /UseOutlines} + % + % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). + \def\dopdfimage#1#2#3{% + \def\pdfimagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% + \def\pdfimageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% + % + % pdftex (and the PDF format) support .pdf, .png, .jpg (among + % others). Let's try in that order, PDF first since if + % someone has a scalable image, presumably better to use that than a + % bitmap. + \let\pdfimgext=\empty + \begingroup + \openin 1 #1.pdf \ifeof 1 + \openin 1 #1.PDF \ifeof 1 + \openin 1 #1.png \ifeof 1 + \openin 1 #1.jpg \ifeof 1 + \openin 1 #1.jpeg \ifeof 1 + \openin 1 #1.JPG \ifeof 1 + \errhelp = \nopdfimagehelp + \errmessage{Could not find image file #1 for pdf}% + \else \gdef\pdfimgext{JPG}% + \fi + \else \gdef\pdfimgext{jpeg}% + \fi + \else \gdef\pdfimgext{jpg}% + \fi + \else \gdef\pdfimgext{png}% + \fi + \else \gdef\pdfimgext{PDF}% + \fi + \else \gdef\pdfimgext{pdf}% + \fi + \closein 1 + \endgroup + % + % without \immediate, ancient pdftex seg faults when the same image is + % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) + \ifnum\pdftexversion < 14 + \immediate\pdfimage + \else + \immediate\pdfximage + \fi + \ifdim \wd0 >0pt width \pdfimagewidth \fi + \ifdim \wd2 >0pt height \pdfimageheight \fi + \ifnum\pdftexversion<13 + #1.\pdfimgext + \else + {#1.\pdfimgext}% + \fi + \ifnum\pdftexversion < 14 \else + \pdfrefximage \pdflastximage + \fi} + % + \def\pdfmkdest#1{{% + % We have to set dummies so commands such as @code, and characters + % such as \, aren't expanded when present in a section title. + \indexnofonts + \turnoffactive + \makevalueexpandable + \def\pdfdestname{#1}% + \txiescapepdf\pdfdestname + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + }} + % + % used to mark target names; must be expandable. + \def\pdfmkpgn#1{#1} + % + % by default, use a color that is dark enough to print on paper as + % nearly black, but still distinguishable for online viewing. + \def\urlcolor{\rgbDarkRed} + \def\linkcolor{\rgbDarkRed} + \def\endlink{\setcolor{\maincolor}\pdfendlink} + % + % Adding outlines to PDF; macros for calculating structure of outlines + % come from Petr Olsak + \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% + \else \csname#1\endcsname \fi} + \def\advancenumber#1{\tempnum=\expnumber{#1}\relax + \advance\tempnum by 1 + \expandafter\xdef\csname#1\endcsname{\the\tempnum}} + % + % #1 is the section text, which is what will be displayed in the + % outline by the pdf viewer. #2 is the pdf expression for the number + % of subentries (or empty, for subsubsections). #3 is the node text, + % which might be empty if this toc entry had no corresponding node. + % #4 is the page number + % + \def\dopdfoutline#1#2#3#4{% + % Generate a link to the node text if that exists; else, use the + % page number. We could generate a destination for the section + % text in the case where a section has no node, but it doesn't + % seem worth the trouble, since most documents are normally structured. + \edef\pdfoutlinedest{#3}% + \ifx\pdfoutlinedest\empty + \def\pdfoutlinedest{#4}% + \else + \txiescapepdf\pdfoutlinedest + \fi + % + % Also escape PDF chars in the display string. + \edef\pdfoutlinetext{#1}% + \txiescapepdf\pdfoutlinetext + % + \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% + } + % + \def\pdfmakeoutlines{% + \begingroup + % Read toc silently, to get counts of subentries for \pdfoutline. + \def\partentry##1##2##3##4{}% ignore parts in the outlines + \def\numchapentry##1##2##3##4{% + \def\thischapnum{##2}% + \def\thissecnum{0}% + \def\thissubsecnum{0}% + }% + \def\numsecentry##1##2##3##4{% + \advancenumber{chap\thischapnum}% + \def\thissecnum{##2}% + \def\thissubsecnum{0}% + }% + \def\numsubsecentry##1##2##3##4{% + \advancenumber{sec\thissecnum}% + \def\thissubsecnum{##2}% + }% + \def\numsubsubsecentry##1##2##3##4{% + \advancenumber{subsec\thissubsecnum}% + }% + \def\thischapnum{0}% + \def\thissecnum{0}% + \def\thissubsecnum{0}% + % + % use \def rather than \let here because we redefine \chapentry et + % al. a second time, below. + \def\appentry{\numchapentry}% + \def\appsecentry{\numsecentry}% + \def\appsubsecentry{\numsubsecentry}% + \def\appsubsubsecentry{\numsubsubsecentry}% + \def\unnchapentry{\numchapentry}% + \def\unnsecentry{\numsecentry}% + \def\unnsubsecentry{\numsubsecentry}% + \def\unnsubsubsecentry{\numsubsubsecentry}% + \readdatafile{toc}% + % + % Read toc second time, this time actually producing the outlines. + % The `-' means take the \expnumber as the absolute number of + % subentries, which we calculated on our first read of the .toc above. + % + % We use the node names as the destinations. + \def\numchapentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% + \def\numsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% + \def\numsubsecentry##1##2##3##4{% + \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% + \def\numsubsubsecentry##1##2##3##4{% count is always zero + \dopdfoutline{##1}{}{##3}{##4}}% + % + % PDF outlines are displayed using system fonts, instead of + % document fonts. Therefore we cannot use special characters, + % since the encoding is unknown. For example, the eogonek from + % Latin 2 (0xea) gets translated to a | character. Info from + % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. + % + % TODO this right, we have to translate 8-bit characters to + % their "best" equivalent, based on the @documentencoding. Too + % much work for too little return. Just use the ASCII equivalents + % we use for the index sort strings. + % + \indexnofonts + \setupdatafile + % We can have normal brace characters in the PDF outlines, unlike + % Texinfo index files. So set that up. + \def\{{\lbracecharliteral}% + \def\}{\rbracecharliteral}% + \catcode`\\=\active \otherbackslash + \input \tocreadfilename + \endgroup + } + {\catcode`[=1 \catcode`]=2 + \catcode`{=\other \catcode`}=\other + \gdef\lbracecharliteral[{]% + \gdef\rbracecharliteral[}]% + ] + % + \def\skipspaces#1{\def\PP{#1}\def\D{|}% + \ifx\PP\D\let\nextsp\relax + \else\let\nextsp\skipspaces + \addtokens{\filename}{\PP}% + \advance\filenamelength by 1 + \fi + \nextsp} + \def\getfilename#1{% + \filenamelength=0 + % If we don't expand the argument now, \skipspaces will get + % snagged on things like "@value{foo}". + \edef\temp{#1}% + \expandafter\skipspaces\temp|\relax + } + \ifnum\pdftexversion < 14 + \let \startlink \pdfannotlink + \else + \let \startlink \pdfstartlink + \fi + % make a live url in pdf output. + \def\pdfurl#1{% + \begingroup + % it seems we really need yet another set of dummies; have not + % tried to figure out what each command should do in the context + % of @url. for now, just make @/ a no-op, that's the only one + % people have actually reported a problem with. + % + \normalturnoffactive + \def\@{@}% + \let\/=\empty + \makevalueexpandable + % do we want to go so far as to use \indexnofonts instead of just + % special-casing \var here? + \def\var##1{##1}% + % + \leavevmode\setcolor{\urlcolor}% + \startlink attr{/Border [0 0 0]}% + user{/Subtype /Link /A << /S /URI /URI (#1) >>}% + \endgroup} + \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} + \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} + \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} + \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} + \def\maketoks{% + \expandafter\poptoks\the\toksA|ENDTOKS|\relax + \ifx\first0\adn0 + \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 + \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 + \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 + \else + \ifnum0=\countA\else\makelink\fi + \ifx\first.\let\next=\done\else + \let\next=\maketoks + \addtokens{\toksB}{\the\toksD} + \ifx\first,\addtokens{\toksB}{\space}\fi + \fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \next} + \def\makelink{\addtokens{\toksB}% + {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} + \def\pdflink#1{% + \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} + \setcolor{\linkcolor}#1\endlink} + \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} +\else + % non-pdf mode + \let\pdfmkdest = \gobble + \let\pdfurl = \gobble + \let\endlink = \relax + \let\setcolor = \gobble + \let\pdfsetcolor = \gobble + \let\pdfmakeoutlines = \relax +\fi % \ifx\pdfoutput + + +\message{fonts,} + +% Change the current font style to #1, remembering it in \curfontstyle. +% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in +% italics, not bold italics. +% +\def\setfontstyle#1{% + \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. + \csname ten#1\endcsname % change the current font +} + +% Select #1 fonts with the current style. +% +\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} + +\def\rm{\fam=0 \setfontstyle{rm}} +\def\it{\fam=\itfam \setfontstyle{it}} +\def\sl{\fam=\slfam \setfontstyle{sl}} +\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} +\def\tt{\fam=\ttfam \setfontstyle{tt}} + +% Unfortunately, we have to override this for titles and the like, since +% in those cases "rm" is bold. Sigh. +\def\rmisbold{\rm\def\curfontstyle{bf}} + +% Texinfo sort of supports the sans serif font style, which plain TeX does not. +% So we set up a \sf. +\newfam\sffam +\def\sf{\fam=\sffam \setfontstyle{sf}} +\let\li = \sf % Sometimes we call it \li, not \sf. + +% We don't need math for this font style. +\def\ttsl{\setfontstyle{ttsl}} + + +% Set the baselineskip to #1, and the lineskip and strut size +% correspondingly. There is no deep meaning behind these magic numbers +% used as factors; they just match (closely enough) what Knuth defined. +% +\def\lineskipfactor{.08333} +\def\strutheightpercent{.70833} +\def\strutdepthpercent {.29167} +% +% can get a sort of poor man's double spacing by redefining this. +\def\baselinefactor{1} +% +\newdimen\textleading +\def\setleading#1{% + \dimen0 = #1\relax + \normalbaselineskip = \baselinefactor\dimen0 + \normallineskip = \lineskipfactor\normalbaselineskip + \normalbaselines + \setbox\strutbox =\hbox{% + \vrule width0pt height\strutheightpercent\baselineskip + depth \strutdepthpercent \baselineskip + }% +} + +% PDF CMaps. See also LaTeX's t1.cmap. +% +% do nothing with this by default. +\expandafter\let\csname cmapOT1\endcsname\gobble +\expandafter\let\csname cmapOT1IT\endcsname\gobble +\expandafter\let\csname cmapOT1TT\endcsname\gobble + +% if we are producing pdf, and we have \pdffontattr, then define cmaps. +% (\pdffontattr was introduced many years ago, but people still run +% older pdftex's; it's easy to conditionalize, so we do.) +\ifpdf \ifx\pdffontattr\thisisundefined \else + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1-0) +%%Title: (TeX-OT1-0 TeX OT1 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1) +/Supplement 0 +>> def +/CMapName /TeX-OT1-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +8 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<23> <26> <0023> +<28> <3B> <0028> +<3F> <5B> <003F> +<5D> <5E> <005D> +<61> <7A> <0061> +<7B> <7C> <2013> +endbfrange +40 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <00660066> +<0C> <00660069> +<0D> <0066006C> +<0E> <006600660069> +<0F> <00660066006C> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<21> <0021> +<22> <201D> +<27> <2019> +<3C> <00A1> +<3D> <003D> +<3E> <00BF> +<5C> <201C> +<5F> <02D9> +<60> <2018> +<7D> <02DD> +<7E> <007E> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +% +% \cmapOT1IT + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1IT-0) +%%Title: (TeX-OT1IT-0 TeX OT1IT 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1IT) +/Supplement 0 +>> def +/CMapName /TeX-OT1IT-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +8 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<25> <26> <0025> +<28> <3B> <0028> +<3F> <5B> <003F> +<5D> <5E> <005D> +<61> <7A> <0061> +<7B> <7C> <2013> +endbfrange +42 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <00660066> +<0C> <00660069> +<0D> <0066006C> +<0E> <006600660069> +<0F> <00660066006C> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<21> <0021> +<22> <201D> +<23> <0023> +<24> <00A3> +<27> <2019> +<3C> <00A1> +<3D> <003D> +<3E> <00BF> +<5C> <201C> +<5F> <02D9> +<60> <2018> +<7D> <02DD> +<7E> <007E> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1IT\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +% +% \cmapOT1TT + \begingroup + \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. + \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap +%%DocumentNeededResources: ProcSet (CIDInit) +%%IncludeResource: ProcSet (CIDInit) +%%BeginResource: CMap (TeX-OT1TT-0) +%%Title: (TeX-OT1TT-0 TeX OT1TT 0) +%%Version: 1.000 +%%EndComments +/CIDInit /ProcSet findresource begin +12 dict begin +begincmap +/CIDSystemInfo +<< /Registry (TeX) +/Ordering (OT1TT) +/Supplement 0 +>> def +/CMapName /TeX-OT1TT-0 def +/CMapType 2 def +1 begincodespacerange +<00> <7F> +endcodespacerange +5 beginbfrange +<00> <01> <0393> +<09> <0A> <03A8> +<21> <26> <0021> +<28> <5F> <0028> +<61> <7E> <0061> +endbfrange +32 beginbfchar +<02> <0398> +<03> <039B> +<04> <039E> +<05> <03A0> +<06> <03A3> +<07> <03D2> +<08> <03A6> +<0B> <2191> +<0C> <2193> +<0D> <0027> +<0E> <00A1> +<0F> <00BF> +<10> <0131> +<11> <0237> +<12> <0060> +<13> <00B4> +<14> <02C7> +<15> <02D8> +<16> <00AF> +<17> <02DA> +<18> <00B8> +<19> <00DF> +<1A> <00E6> +<1B> <0153> +<1C> <00F8> +<1D> <00C6> +<1E> <0152> +<1F> <00D8> +<20> <2423> +<27> <2019> +<60> <2018> +<7F> <00A8> +endbfchar +endcmap +CMapName currentdict /CMap defineresource pop +end +end +%%EndResource +%%EOF + }\endgroup + \expandafter\edef\csname cmapOT1TT\endcsname#1{% + \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% + }% +\fi\fi + + +% Set the font macro #1 to the font named \fontprefix#2. +% #3 is the font's design size, #4 is a scale factor, #5 is the CMap +% encoding (only OT1, OT1IT and OT1TT are allowed, or empty to omit). +% Example: +% #1 = \textrm +% #2 = \rmshape +% #3 = 10 +% #4 = \mainmagstep +% #5 = OT1 +% +\def\setfont#1#2#3#4#5{% + \font#1=\fontprefix#2#3 scaled #4 + \csname cmap#5\endcsname#1% +} +% This is what gets called when #5 of \setfont is empty. +\let\cmap\gobble +% +% (end of cmaps) + +% Use cm as the default font prefix. +% To specify the font prefix, you must define \fontprefix +% before you read in texinfo.tex. +\ifx\fontprefix\thisisundefined +\def\fontprefix{cm} +\fi +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} % where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} + +% Definitions for a main text size of 11pt. (The default in Texinfo.) +% +\def\definetextfontsizexi{% +% Text fonts (11.2pt, magstep1). +\def\textnominalsize{11pt} +\edef\mainmagstep{\magstephalf} +\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} +\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} +\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} +\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} +\setfont\textsl\slshape{10}{\mainmagstep}{OT1} +\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} +\setfont\textsc\scshape{10}{\mainmagstep}{OT1} +\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep +\def\textecsize{1095} + +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstep1}{OT1} +\setfont\deftt\ttshape{10}{\magstep1}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} + +% Fonts for indices, footnotes, small examples (9pt). +\def\smallnominalsize{9pt} +\setfont\smallrm\rmshape{9}{1000}{OT1} +\setfont\smalltt\ttshape{9}{1000}{OT1TT} +\setfont\smallbf\bfshape{10}{900}{OT1} +\setfont\smallit\itshape{9}{1000}{OT1IT} +\setfont\smallsl\slshape{9}{1000}{OT1} +\setfont\smallsf\sfshape{9}{1000}{OT1} +\setfont\smallsc\scshape{10}{900}{OT1} +\setfont\smallttsl\ttslshape{10}{900}{OT1TT} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 +\def\smallecsize{0900} + +% Fonts for small examples (8pt). +\def\smallernominalsize{8pt} +\setfont\smallerrm\rmshape{8}{1000}{OT1} +\setfont\smallertt\ttshape{8}{1000}{OT1TT} +\setfont\smallerbf\bfshape{10}{800}{OT1} +\setfont\smallerit\itshape{8}{1000}{OT1IT} +\setfont\smallersl\slshape{8}{1000}{OT1} +\setfont\smallersf\sfshape{8}{1000}{OT1} +\setfont\smallersc\scshape{10}{800}{OT1} +\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 +\def\smallerecsize{0800} + +% Fonts for title page (20.4pt): +\def\titlenominalsize{20pt} +\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} +\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} +\setfont\titlesl\slbshape{10}{\magstep4}{OT1} +\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} +\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} +\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4}{OT1} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\titleecsize{2074} + +% Chapter (and unnumbered) fonts (17.28pt). +\def\chapnominalsize{17pt} +\setfont\chaprm\rmbshape{12}{\magstep2}{OT1} +\setfont\chapit\itbshape{10}{\magstep3}{OT1IT} +\setfont\chapsl\slbshape{10}{\magstep3}{OT1} +\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT} +\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT} +\setfont\chapsf\sfbshape{17}{1000}{OT1} +\let\chapbf=\chaprm +\setfont\chapsc\scbshape{10}{\magstep3}{OT1} +\font\chapi=cmmi12 scaled \magstep2 +\font\chapsy=cmsy10 scaled \magstep3 +\def\chapecsize{1728} + +% Section fonts (14.4pt). +\def\secnominalsize{14pt} +\setfont\secrm\rmbshape{12}{\magstep1}{OT1} +\setfont\secit\itbshape{10}{\magstep2}{OT1IT} +\setfont\secsl\slbshape{10}{\magstep2}{OT1} +\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} +\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT} +\setfont\secsf\sfbshape{12}{\magstep1}{OT1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2}{OT1} +\font\seci=cmmi12 scaled \magstep1 +\font\secsy=cmsy10 scaled \magstep2 +\def\sececsize{1440} + +% Subsection fonts (13.15pt). +\def\ssecnominalsize{13pt} +\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1} +\setfont\ssecit\itbshape{10}{1315}{OT1IT} +\setfont\ssecsl\slbshape{10}{1315}{OT1} +\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT} +\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT} +\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{1315}{OT1} +\font\sseci=cmmi12 scaled \magstephalf +\font\ssecsy=cmsy10 scaled 1315 +\def\ssececsize{1200} + +% Reduced fonts for @acro in text (10pt). +\def\reducednominalsize{10pt} +\setfont\reducedrm\rmshape{10}{1000}{OT1} +\setfont\reducedtt\ttshape{10}{1000}{OT1TT} +\setfont\reducedbf\bfshape{10}{1000}{OT1} +\setfont\reducedit\itshape{10}{1000}{OT1IT} +\setfont\reducedsl\slshape{10}{1000}{OT1} +\setfont\reducedsf\sfshape{10}{1000}{OT1} +\setfont\reducedsc\scshape{10}{1000}{OT1} +\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT} +\font\reducedi=cmmi10 +\font\reducedsy=cmsy10 +\def\reducedecsize{1000} + +\textleading = 13.2pt % line spacing for 11pt CM +\textfonts % reset the current fonts +\rm +} % end of 11pt text font size definitions, \definetextfontsizexi + + +% Definitions to make the main text be 10pt Computer Modern, with +% section, chapter, etc., sizes following suit. This is for the GNU +% Press printing of the Emacs 22 manual. Maybe other manuals in the +% future. Used with @smallbook, which sets the leading to 12pt. +% +\def\definetextfontsizex{% +% Text fonts (10pt). +\def\textnominalsize{10pt} +\edef\mainmagstep{1000} +\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} +\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} +\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} +\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} +\setfont\textsl\slshape{10}{\mainmagstep}{OT1} +\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} +\setfont\textsc\scshape{10}{\mainmagstep}{OT1} +\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} +\font\texti=cmmi10 scaled \mainmagstep +\font\textsy=cmsy10 scaled \mainmagstep +\def\textecsize{1000} + +% A few fonts for @defun names and args. +\setfont\defbf\bfshape{10}{\magstephalf}{OT1} +\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} +\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} +\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} + +% Fonts for indices, footnotes, small examples (9pt). +\def\smallnominalsize{9pt} +\setfont\smallrm\rmshape{9}{1000}{OT1} +\setfont\smalltt\ttshape{9}{1000}{OT1TT} +\setfont\smallbf\bfshape{10}{900}{OT1} +\setfont\smallit\itshape{9}{1000}{OT1IT} +\setfont\smallsl\slshape{9}{1000}{OT1} +\setfont\smallsf\sfshape{9}{1000}{OT1} +\setfont\smallsc\scshape{10}{900}{OT1} +\setfont\smallttsl\ttslshape{10}{900}{OT1TT} +\font\smalli=cmmi9 +\font\smallsy=cmsy9 +\def\smallecsize{0900} + +% Fonts for small examples (8pt). +\def\smallernominalsize{8pt} +\setfont\smallerrm\rmshape{8}{1000}{OT1} +\setfont\smallertt\ttshape{8}{1000}{OT1TT} +\setfont\smallerbf\bfshape{10}{800}{OT1} +\setfont\smallerit\itshape{8}{1000}{OT1IT} +\setfont\smallersl\slshape{8}{1000}{OT1} +\setfont\smallersf\sfshape{8}{1000}{OT1} +\setfont\smallersc\scshape{10}{800}{OT1} +\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} +\font\smalleri=cmmi8 +\font\smallersy=cmsy8 +\def\smallerecsize{0800} + +% Fonts for title page (20.4pt): +\def\titlenominalsize{20pt} +\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} +\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} +\setfont\titlesl\slbshape{10}{\magstep4}{OT1} +\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} +\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} +\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4}{OT1} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\titleecsize{2074} + +% Chapter fonts (14.4pt). +\def\chapnominalsize{14pt} +\setfont\chaprm\rmbshape{12}{\magstep1}{OT1} +\setfont\chapit\itbshape{10}{\magstep2}{OT1IT} +\setfont\chapsl\slbshape{10}{\magstep2}{OT1} +\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT} +\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT} +\setfont\chapsf\sfbshape{12}{\magstep1}{OT1} +\let\chapbf\chaprm +\setfont\chapsc\scbshape{10}{\magstep2}{OT1} +\font\chapi=cmmi12 scaled \magstep1 +\font\chapsy=cmsy10 scaled \magstep2 +\def\chapecsize{1440} + +% Section fonts (12pt). +\def\secnominalsize{12pt} +\setfont\secrm\rmbshape{12}{1000}{OT1} +\setfont\secit\itbshape{10}{\magstep1}{OT1IT} +\setfont\secsl\slbshape{10}{\magstep1}{OT1} +\setfont\sectt\ttbshape{12}{1000}{OT1TT} +\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT} +\setfont\secsf\sfbshape{12}{1000}{OT1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep1}{OT1} +\font\seci=cmmi12 +\font\secsy=cmsy10 scaled \magstep1 +\def\sececsize{1200} + +% Subsection fonts (10pt). +\def\ssecnominalsize{10pt} +\setfont\ssecrm\rmbshape{10}{1000}{OT1} +\setfont\ssecit\itbshape{10}{1000}{OT1IT} +\setfont\ssecsl\slbshape{10}{1000}{OT1} +\setfont\ssectt\ttbshape{10}{1000}{OT1TT} +\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT} +\setfont\ssecsf\sfbshape{10}{1000}{OT1} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{1000}{OT1} +\font\sseci=cmmi10 +\font\ssecsy=cmsy10 +\def\ssececsize{1000} + +% Reduced fonts for @acro in text (9pt). +\def\reducednominalsize{9pt} +\setfont\reducedrm\rmshape{9}{1000}{OT1} +\setfont\reducedtt\ttshape{9}{1000}{OT1TT} +\setfont\reducedbf\bfshape{10}{900}{OT1} +\setfont\reducedit\itshape{9}{1000}{OT1IT} +\setfont\reducedsl\slshape{9}{1000}{OT1} +\setfont\reducedsf\sfshape{9}{1000}{OT1} +\setfont\reducedsc\scshape{10}{900}{OT1} +\setfont\reducedttsl\ttslshape{10}{900}{OT1TT} +\font\reducedi=cmmi9 +\font\reducedsy=cmsy9 +\def\reducedecsize{0900} + +\divide\parskip by 2 % reduce space between paragraphs +\textleading = 12pt % line spacing for 10pt CM +\textfonts % reset the current fonts +\rm +} % end of 10pt text font size definitions, \definetextfontsizex + + +% We provide the user-level command +% @fonttextsize 10 +% (or 11) to redefine the text font size. pt is assumed. +% +\def\xiword{11} +\def\xword{10} +\def\xwordpt{10pt} +% +\parseargdef\fonttextsize{% + \def\textsizearg{#1}% + %\wlog{doing @fonttextsize \textsizearg}% + % + % Set \globaldefs so that documents can use this inside @tex, since + % makeinfo 4.8 does not support it, but we need it nonetheless. + % + \begingroup \globaldefs=1 + \ifx\textsizearg\xword \definetextfontsizex + \else \ifx\textsizearg\xiword \definetextfontsizexi + \else + \errhelp=\EMsimple + \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} + \fi\fi + \endgroup +} + + +% In order for the font changes to affect most math symbols and letters, +% we have to define the \textfont of the standard families. Since +% texinfo doesn't allow for producing subscripts and superscripts except +% in the main text, we don't bother to reset \scriptfont and +% \scriptscriptfont (which would also require loading a lot more fonts). +% +\def\resetmathfonts{% + \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy + \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf + \textfont\ttfam=\tentt \textfont\sffam=\tensf +} + +% The font-changing commands redefine the meanings of \tenSTYLE, instead +% of just \STYLE. We do this because \STYLE needs to also set the +% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire +% \tenSTYLE to set the current font. +% +% Each font-changing command also sets the names \lsize (one size lower) +% and \lllsize (three sizes lower). These relative commands are used in +% the LaTeX logo and acronyms. +% +% This all needs generalizing, badly. +% +\def\textfonts{% + \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl + \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tenttsl=\textttsl + \def\curfontsize{text}% + \def\lsize{reduced}\def\lllsize{smaller}% + \resetmathfonts \setleading{\textleading}} +\def\titlefonts{% + \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl + \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc + \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy + \let\tenttsl=\titlettsl + \def\curfontsize{title}% + \def\lsize{chap}\def\lllsize{subsec}% + \resetmathfonts \setleading{27pt}} +\def\titlefont#1{{\titlefonts\rmisbold #1}} +\def\chapfonts{% + \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl + \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy + \let\tenttsl=\chapttsl + \def\curfontsize{chap}% + \def\lsize{sec}\def\lllsize{text}% + \resetmathfonts \setleading{19pt}} +\def\secfonts{% + \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl + \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy + \let\tenttsl=\secttsl + \def\curfontsize{sec}% + \def\lsize{subsec}\def\lllsize{reduced}% + \resetmathfonts \setleading{16pt}} +\def\subsecfonts{% + \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl + \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy + \let\tenttsl=\ssecttsl + \def\curfontsize{ssec}% + \def\lsize{text}\def\lllsize{small}% + \resetmathfonts \setleading{15pt}} +\let\subsubsecfonts = \subsecfonts +\def\reducedfonts{% + \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl + \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc + \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy + \let\tenttsl=\reducedttsl + \def\curfontsize{reduced}% + \def\lsize{small}\def\lllsize{smaller}% + \resetmathfonts \setleading{10.5pt}} +\def\smallfonts{% + \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl + \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc + \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy + \let\tenttsl=\smallttsl + \def\curfontsize{small}% + \def\lsize{smaller}\def\lllsize{smaller}% + \resetmathfonts \setleading{10.5pt}} +\def\smallerfonts{% + \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl + \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc + \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy + \let\tenttsl=\smallerttsl + \def\curfontsize{smaller}% + \def\lsize{smaller}\def\lllsize{smaller}% + \resetmathfonts \setleading{9.5pt}} + +% Fonts for short table of contents. +\setfont\shortcontrm\rmshape{12}{1000}{OT1} +\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 +\setfont\shortcontsl\slshape{12}{1000}{OT1} +\setfont\shortconttt\ttshape{12}{1000}{OT1TT} + +% Define these just so they can be easily changed for other fonts. +\def\angleleft{$\langle$} +\def\angleright{$\rangle$} + +% Set the fonts to use with the @small... environments. +\let\smallexamplefonts = \smallfonts + +% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample +% can fit this many characters: +% 8.5x11=86 smallbook=72 a4=90 a5=69 +% If we use \scriptfonts (8pt), then we can fit this many characters: +% 8.5x11=90+ smallbook=80 a4=90+ a5=77 +% For me, subjectively, the few extra characters that fit aren't worth +% the additional smallness of 8pt. So I'm making the default 9pt. +% +% By the way, for comparison, here's what fits with @example (10pt): +% 8.5x11=71 smallbook=60 a4=75 a5=58 +% --karl, 24jan03. + +% Set up the default fonts, so we can use them for creating boxes. +% +\definetextfontsizexi + + +\message{markup,} + +% Check if we are currently using a typewriter font. Since all the +% Computer Modern typewriter fonts have zero interword stretch (and +% shrink), and it is reasonable to expect all typewriter fonts to have +% this property, we can check that font parameter. +% +\def\ifmonospace{\ifdim\fontdimen3\font=0pt } + +% Markup style infrastructure. \defmarkupstylesetup\INITMACRO will +% define and register \INITMACRO to be called on markup style changes. +% \INITMACRO can check \currentmarkupstyle for the innermost +% style and the set of \ifmarkupSTYLE switches for all styles +% currently in effect. +\newif\ifmarkupvar +\newif\ifmarkupsamp +\newif\ifmarkupkey +%\newif\ifmarkupfile % @file == @samp. +%\newif\ifmarkupoption % @option == @samp. +\newif\ifmarkupcode +\newif\ifmarkupkbd +%\newif\ifmarkupenv % @env == @code. +%\newif\ifmarkupcommand % @command == @code. +\newif\ifmarkuptex % @tex (and part of @math, for now). +\newif\ifmarkupexample +\newif\ifmarkupverb +\newif\ifmarkupverbatim + +\let\currentmarkupstyle\empty + +\def\setupmarkupstyle#1{% + \csname markup#1true\endcsname + \def\currentmarkupstyle{#1}% + \markupstylesetup +} + +\let\markupstylesetup\empty + +\def\defmarkupstylesetup#1{% + \expandafter\def\expandafter\markupstylesetup + \expandafter{\markupstylesetup #1}% + \def#1% +} + +% Markup style setup for left and right quotes. +\defmarkupstylesetup\markupsetuplq{% + \expandafter\let\expandafter \temp + \csname markupsetuplq\currentmarkupstyle\endcsname + \ifx\temp\relax \markupsetuplqdefault \else \temp \fi +} + +\defmarkupstylesetup\markupsetuprq{% + \expandafter\let\expandafter \temp + \csname markupsetuprq\currentmarkupstyle\endcsname + \ifx\temp\relax \markupsetuprqdefault \else \temp \fi +} + +{ +\catcode`\'=\active +\catcode`\`=\active + +\gdef\markupsetuplqdefault{\let`\lq} +\gdef\markupsetuprqdefault{\let'\rq} + +\gdef\markupsetcodequoteleft{\let`\codequoteleft} +\gdef\markupsetcodequoteright{\let'\codequoteright} +} + +\let\markupsetuplqcode \markupsetcodequoteleft +\let\markupsetuprqcode \markupsetcodequoteright +% +\let\markupsetuplqexample \markupsetcodequoteleft +\let\markupsetuprqexample \markupsetcodequoteright +% +\let\markupsetuplqkbd \markupsetcodequoteleft +\let\markupsetuprqkbd \markupsetcodequoteright +% +\let\markupsetuplqsamp \markupsetcodequoteleft +\let\markupsetuprqsamp \markupsetcodequoteright +% +\let\markupsetuplqverb \markupsetcodequoteleft +\let\markupsetuprqverb \markupsetcodequoteright +% +\let\markupsetuplqverbatim \markupsetcodequoteleft +\let\markupsetuprqverbatim \markupsetcodequoteright + +% Allow an option to not use regular directed right quote/apostrophe +% (char 0x27), but instead the undirected quote from cmtt (char 0x0d). +% The undirected quote is ugly, so don't make it the default, but it +% works for pasting with more pdf viewers (at least evince), the +% lilypond developers report. xpdf does work with the regular 0x27. +% +\def\codequoteright{% + \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax + \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax + '% + \else \char'15 \fi + \else \char'15 \fi +} +% +% and a similar option for the left quote char vs. a grave accent. +% Modern fonts display ASCII 0x60 as a grave accent, so some people like +% the code environments to do likewise. +% +\def\codequoteleft{% + \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax + \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax + % [Knuth] pp. 380,381,391 + % \relax disables Spanish ligatures ?` and !` of \tt font. + \relax`% + \else \char'22 \fi + \else \char'22 \fi +} + +% Commands to set the quote options. +% +\parseargdef\codequoteundirected{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxicodequoteundirected\endcsname + = t% + \else\ifx\temp\offword + \expandafter\let\csname SETtxicodequoteundirected\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @codequoteundirected value `\temp', must be on|off}% + \fi\fi +} +% +\parseargdef\codequotebacktick{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxicodequotebacktick\endcsname + = t% + \else\ifx\temp\offword + \expandafter\let\csname SETtxicodequotebacktick\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @codequotebacktick value `\temp', must be on|off}% + \fi\fi +} + +% [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font. +\def\noligaturesquoteleft{\relax\lq} + +% Count depth in font-changes, for error checks +\newcount\fontdepth \fontdepth=0 + +% Font commands. + +% #1 is the font command (\sl or \it), #2 is the text to slant. +% If we are in a monospaced environment, however, 1) always use \ttsl, +% and 2) do not add an italic correction. +\def\dosmartslant#1#2{% + \ifusingtt + {{\ttsl #2}\let\next=\relax}% + {\def\next{{#1#2}\futurelet\next\smartitaliccorrection}}% + \next +} +\def\smartslanted{\dosmartslant\sl} +\def\smartitalic{\dosmartslant\it} + +% Output an italic correction unless \next (presumed to be the following +% character) is such as not to need one. +\def\smartitaliccorrection{% + \ifx\next,% + \else\ifx\next-% + \else\ifx\next.% + \else\ptexslash + \fi\fi\fi + \aftersmartic +} + +% Unconditional use \ttsl, and no ic. @var is set to this for defuns. +\def\ttslanted#1{{\ttsl #1}} + +% @cite is like \smartslanted except unconditionally use \sl. We never want +% ttsl for book titles, do we? +\def\cite#1{{\sl #1}\futurelet\next\smartitaliccorrection} + +\def\aftersmartic{} +\def\var#1{% + \let\saveaftersmartic = \aftersmartic + \def\aftersmartic{\null\let\aftersmartic=\saveaftersmartic}% + \smartslanted{#1}% +} + +\let\i=\smartitalic +\let\slanted=\smartslanted +\let\dfn=\smartslanted +\let\emph=\smartitalic + +% Explicit font changes: @r, @sc, undocumented @ii. +\def\r#1{{\rm #1}} % roman font +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +% @b, explicit bold. Also @strong. +\def\b#1{{\bf #1}} +\let\strong=\b + +% @sansserif, explicit sans. +\def\sansserif#1{{\sf #1}} + +% We can't just use \exhyphenpenalty, because that only has effect at +% the end of a paragraph. Restore normal hyphenation at the end of the +% group within which \nohyphenation is presumably called. +% +\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} +\def\restorehyphenation{\hyphenchar\font = `- } + +% Set sfcode to normal for the chars that usually have another value. +% Can't use plain's \frenchspacing because it uses the `\x notation, and +% sometimes \x has an active definition that messes things up. +% +\catcode`@=11 + \def\plainfrenchspacing{% + \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m + \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m + \def\endofsentencespacefactor{1000}% for @. and friends + } + \def\plainnonfrenchspacing{% + \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 + \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 + \def\endofsentencespacefactor{3000}% for @. and friends + } +\catcode`@=\other +\def\endofsentencespacefactor{3000}% default + +% @t, explicit typewriter. +\def\t#1{% + {\tt \rawbackslash \plainfrenchspacing #1}% + \null +} + +% @samp. +\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}} + +% @indicateurl is \samp, that is, with quotes. +\let\indicateurl=\samp + +% @code (and similar) prints in typewriter, but with spaces the same +% size as normal in the surrounding text, without hyphenation, etc. +% This is a subroutine for that. +\def\tclose#1{% + {% + % Change normal interword space to be same as for the current font. + \spaceskip = \fontdimen2\font + % + % Switch to typewriter. + \tt + % + % But `\ ' produces the large typewriter interword space. + \def\ {{\spaceskip = 0pt{} }}% + % + % Turn off hyphenation. + \nohyphenation + % + \rawbackslash + \plainfrenchspacing + #1% + }% + \null % reset spacefactor to 1000 +} + +% We *must* turn on hyphenation at `-' and `_' in @code. +% Otherwise, it is too hard to avoid overfull hboxes +% in the Emacs manual, the Library manual, etc. +% +% Unfortunately, TeX uses one parameter (\hyphenchar) to control +% both hyphenation at - and hyphenation within words. +% We must therefore turn them both off (\tclose does that) +% and arrange explicitly to hyphenate at a dash. +% -- rms. +{ + \catcode`\-=\active \catcode`\_=\active + \catcode`\'=\active \catcode`\`=\active + \global\let'=\rq \global\let`=\lq % default definitions + % + \global\def\code{\begingroup + \setupmarkupstyle{code}% + % The following should really be moved into \setupmarkupstyle handlers. + \catcode\dashChar=\active \catcode\underChar=\active + \ifallowcodebreaks + \let-\codedash + \let_\codeunder + \else + \let-\normaldash + \let_\realunder + \fi + \codex + } +} + +\def\codex #1{\tclose{#1}\endgroup} + +\def\normaldash{-} +\def\codedash{-\discretionary{}{}{}} +\def\codeunder{% + % this is all so @math{@code{var_name}+1} can work. In math mode, _ + % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) + % will therefore expand the active definition of _, which is us + % (inside @code that is), therefore an endless loop. + \ifusingtt{\ifmmode + \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. + \else\normalunderscore \fi + \discretionary{}{}{}}% + {\_}% +} + +% An additional complication: the above will allow breaks after, e.g., +% each of the four underscores in __typeof__. This is bad. +% @allowcodebreaks provides a document-level way to turn breaking at - +% and _ on and off. +% +\newif\ifallowcodebreaks \allowcodebreakstrue + +\def\keywordtrue{true} +\def\keywordfalse{false} + +\parseargdef\allowcodebreaks{% + \def\txiarg{#1}% + \ifx\txiarg\keywordtrue + \allowcodebreakstrue + \else\ifx\txiarg\keywordfalse + \allowcodebreaksfalse + \else + \errhelp = \EMsimple + \errmessage{Unknown @allowcodebreaks option `\txiarg', must be true|false}% + \fi\fi +} + +% For @command, @env, @file, @option quotes seem unnecessary, +% so use \code rather than \samp. +\let\command=\code +\let\env=\code +\let\file=\code +\let\option=\code + +% @uref (abbreviation for `urlref') takes an optional (comma-separated) +% second argument specifying the text to display and an optional third +% arg as text to display instead of (rather than in addition to) the url +% itself. First (mandatory) arg is the url. +% (This \urefnobreak definition isn't used now, leaving it for a while +% for comparison.) +\def\urefnobreak#1{\dourefnobreak #1,,,\finish} +\def\dourefnobreak#1,#2,#3,#4\finish{\begingroup + \unsepspaces + \pdfurl{#1}% + \setbox0 = \hbox{\ignorespaces #3}% + \ifdim\wd0 > 0pt + \unhbox0 % third arg given, show only that + \else + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \ifpdf + \unhbox0 % PDF: 2nd arg given, show only it + \else + \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url + \fi + \else + \code{#1}% only url given, so show it + \fi + \fi + \endlink +\endgroup} + +% This \urefbreak definition is the active one. +\def\urefbreak{\begingroup \urefcatcodes \dourefbreak} +\let\uref=\urefbreak +\def\dourefbreak#1{\urefbreakfinish #1,,,\finish} +\def\urefbreakfinish#1,#2,#3,#4\finish{% doesn't work in @example + \unsepspaces + \pdfurl{#1}% + \setbox0 = \hbox{\ignorespaces #3}% + \ifdim\wd0 > 0pt + \unhbox0 % third arg given, show only that + \else + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \ifpdf + \unhbox0 % PDF: 2nd arg given, show only it + \else + \unhbox0\ (\urefcode{#1})% DVI: 2nd arg given, show both it and url + \fi + \else + \urefcode{#1}% only url given, so show it + \fi + \fi + \endlink +\endgroup} + +% Allow line breaks around only a few characters (only). +\def\urefcatcodes{% + \catcode\ampChar=\active \catcode\dotChar=\active + \catcode\hashChar=\active \catcode\questChar=\active + \catcode\slashChar=\active +} +{ + \urefcatcodes + % + \global\def\urefcode{\begingroup + \setupmarkupstyle{code}% + \urefcatcodes + \let&\urefcodeamp + \let.\urefcodedot + \let#\urefcodehash + \let?\urefcodequest + \let/\urefcodeslash + \codex + } + % + % By default, they are just regular characters. + \global\def&{\normalamp} + \global\def.{\normaldot} + \global\def#{\normalhash} + \global\def?{\normalquest} + \global\def/{\normalslash} +} + +% we put a little stretch before and after the breakable chars, to help +% line breaking of long url's. The unequal skips make look better in +% cmtt at least, especially for dots. +\def\urefprestretch{\urefprebreak \hskip0pt plus.13em } +\def\urefpoststretch{\urefpostbreak \hskip0pt plus.1em } +% +\def\urefcodeamp{\urefprestretch \&\urefpoststretch} +\def\urefcodedot{\urefprestretch .\urefpoststretch} +\def\urefcodehash{\urefprestretch \#\urefpoststretch} +\def\urefcodequest{\urefprestretch ?\urefpoststretch} +\def\urefcodeslash{\futurelet\next\urefcodeslashfinish} +{ + \catcode`\/=\active + \global\def\urefcodeslashfinish{% + \urefprestretch \slashChar + % Allow line break only after the final / in a sequence of + % slashes, to avoid line break between the slashes in http://. + \ifx\next/\else \urefpoststretch \fi + } +} + +% One more complication: by default we'll break after the special +% characters, but some people like to break before the special chars, so +% allow that. Also allow no breaking at all, for manual control. +% +\parseargdef\urefbreakstyle{% + \def\txiarg{#1}% + \ifx\txiarg\wordnone + \def\urefprebreak{\nobreak}\def\urefpostbreak{\nobreak} + \else\ifx\txiarg\wordbefore + \def\urefprebreak{\allowbreak}\def\urefpostbreak{\nobreak} + \else\ifx\txiarg\wordafter + \def\urefprebreak{\nobreak}\def\urefpostbreak{\allowbreak} + \else + \errhelp = \EMsimple + \errmessage{Unknown @urefbreakstyle setting `\txiarg'}% + \fi\fi\fi +} +\def\wordafter{after} +\def\wordbefore{before} +\def\wordnone{none} + +\urefbreakstyle after + +% @url synonym for @uref, since that's how everyone uses it. +% +\let\url=\uref + +% rms does not like angle brackets --karl, 17may97. +% So now @email is just like @uref, unless we are pdf. +% +%\def\email#1{\angleleft{\tt #1}\angleright} +\ifpdf + \def\email#1{\doemail#1,,\finish} + \def\doemail#1,#2,#3\finish{\begingroup + \unsepspaces + \pdfurl{mailto:#1}% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi + \endlink + \endgroup} +\else + \let\email=\uref +\fi + +% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), +% `example' (@kbd uses ttsl only inside of @example and friends), +% or `code' (@kbd uses normal tty font always). +\parseargdef\kbdinputstyle{% + \def\txiarg{#1}% + \ifx\txiarg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\txiarg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\txiarg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle setting `\txiarg'}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is `distinct'. +\kbdinputstyle distinct + +% @kbd is like @code, except that if the argument is just one @key command, +% then @kbd has no effect. +\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}} + +\def\xkey{\key} +\def\kbdsub#1#2#3\par{% + \def\one{#1}\def\three{#3}\def\threex{??}% + \ifx\one\xkey\ifx\threex\three \key{#2}% + \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi + \else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi +} + +% definition of @key that produces a lozenge. Doesn't adjust to text size. +%\setfont\keyrm\rmshape{8}{1000}{OT1} +%\font\keysy=cmsy9 +%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% +% \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% +% \vbox{\hrule\kern-0.4pt +% \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% +% \kern-0.4pt\hrule}% +% \kern-.06em\raise0.4pt\hbox{\angleright}}}} + +% definition of @key with no lozenge. If the current font is already +% monospace, don't change it; that way, we respect @kbdinputstyle. But +% if it isn't monospace, then use \tt. +% +\def\key#1{{\setupmarkupstyle{key}% + \nohyphenation + \ifmonospace\else\tt\fi + #1}\null} + +% @clicksequence{File @click{} Open ...} +\def\clicksequence#1{\begingroup #1\endgroup} + +% @clickstyle @arrow (by default) +\parseargdef\clickstyle{\def\click{#1}} +\def\click{\arrow} + +% Typeset a dimension, e.g., `in' or `pt'. The only reason for the +% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. +% +\def\dmn#1{\thinspace #1} + +% @l was never documented to mean ``switch to the Lisp font'', +% and it is not used as such in any manual I can find. We need it for +% Polish suppressed-l. --karl, 22sep96. +%\def\l#1{{\li #1}\null} + +% @acronym for "FBI", "NATO", and the like. +% We print this one point size smaller, since it's intended for +% all-uppercase. +% +\def\acronym#1{\doacronym #1,,\finish} +\def\doacronym#1,#2,#3\finish{% + {\selectfonts\lsize #1}% + \def\temp{#2}% + \ifx\temp\empty \else + \space ({\unsepspaces \ignorespaces \temp \unskip})% + \fi + \null % reset \spacefactor=1000 +} + +% @abbr for "Comput. J." and the like. +% No font change, but don't do end-of-sentence spacing. +% +\def\abbr#1{\doabbr #1,,\finish} +\def\doabbr#1,#2,#3\finish{% + {\plainfrenchspacing #1}% + \def\temp{#2}% + \ifx\temp\empty \else + \space ({\unsepspaces \ignorespaces \temp \unskip})% + \fi + \null % reset \spacefactor=1000 +} + +% @asis just yields its argument. Used with @table, for example. +% +\def\asis#1{#1} + +% @math outputs its argument in math mode. +% +% One complication: _ usually means subscripts, but it could also mean +% an actual _ character, as in @math{@var{some_variable} + 1}. So make +% _ active, and distinguish by seeing if the current family is \slfam, +% which is what @var uses. +{ + \catcode`\_ = \active + \gdef\mathunderscore{% + \catcode`\_=\active + \def_{\ifnum\fam=\slfam \_\else\sb\fi}% + } +} +% Another complication: we want \\ (and @\) to output a math (or tt) \. +% FYI, plain.tex uses \\ as a temporary control sequence (for no +% particular reason), but this is not advertised and we don't care. +% +% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. +\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} +% +\def\math{% + \tex + \mathunderscore + \let\\ = \mathbackslash + \mathactive + % make the texinfo accent commands work in math mode + \let\"=\ddot + \let\'=\acute + \let\==\bar + \let\^=\hat + \let\`=\grave + \let\u=\breve + \let\v=\check + \let\~=\tilde + \let\dotaccent=\dot + $\finishmath +} +\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. + +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an argument +% to a command which sets the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \catcode`' = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + \let' = \ptexquoteright + } +} + +% ctrl is no longer a Texinfo command, but leave this definition for fun. +\def\ctrl #1{{\tt \rawbackslash \hat}#1} + +% @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}. +% Ignore unless FMTNAME == tex; then it is like @iftex and @tex, +% except specified as a normal braced arg, so no newlines to worry about. +% +\def\outfmtnametex{tex} +% +\long\def\inlinefmt#1{\doinlinefmt #1,\finish} +\long\def\doinlinefmt#1,#2,\finish{% + \def\inlinefmtname{#1}% + \ifx\inlinefmtname\outfmtnametex \ignorespaces #2\fi +} +% For raw, must switch into @tex before parsing the argument, to avoid +% setting catcodes prematurely. Doing it this way means that, for +% example, @inlineraw{html, foo{bar} gets a parse error instead of being +% ignored. But this isn't important because if people want a literal +% *right* brace they would have to use a command anyway, so they may as +% well use a command to get a left brace too. We could re-use the +% delimiter character idea from \verb, but it seems like overkill. +% +\long\def\inlineraw{\tex \doinlineraw} +\long\def\doinlineraw#1{\doinlinerawtwo #1,\finish} +\def\doinlinerawtwo#1,#2,\finish{% + \def\inlinerawname{#1}% + \ifx\inlinerawname\outfmtnametex \ignorespaces #2\fi + \endgroup % close group opened by \tex. +} + + +\message{glyphs,} +% and logos. + +% @@ prints an @, as does @atchar{}. +\def\@{\char64 } +\let\atchar=\@ + +% @{ @} @lbracechar{} @rbracechar{} all generate brace characters. +% Unless we're in typewriter, use \ecfont because the CM text fonts do +% not have braces, and we don't want to switch into math. +\def\mylbrace{{\ifmonospace\else\ecfont\fi \char123}} +\def\myrbrace{{\ifmonospace\else\ecfont\fi \char125}} +\let\{=\mylbrace \let\lbracechar=\{ +\let\}=\myrbrace \let\rbracechar=\} +\begingroup + % Definitions to produce \{ and \} commands for indices, + % and @{ and @} for the aux/toc files. + \catcode`\{ = \other \catcode`\} = \other + \catcode`\[ = 1 \catcode`\] = 2 + \catcode`\! = 0 \catcode`\\ = \other + !gdef!lbracecmd[\{]% + !gdef!rbracecmd[\}]% + !gdef!lbraceatcmd[@{]% + !gdef!rbraceatcmd[@}]% +!endgroup + +% @comma{} to avoid , parsing problems. +\let\comma = , + +% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent +% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. +\let\, = \ptexc +\let\dotaccent = \ptexdot +\def\ringaccent#1{{\accent23 #1}} +\let\tieaccent = \ptext +\let\ubaraccent = \ptexb +\let\udotaccent = \d + +% Other special characters: @questiondown @exclamdown @ordf @ordm +% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} +\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} + +% Dotless i and dotless j, used for accents. +\def\imacro{i} +\def\jmacro{j} +\def\dotless#1{% + \def\temp{#1}% + \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi + \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi + \else \errmessage{@dotless can be used only with i or j}% + \fi\fi +} + +% The \TeX{} logo, as in plain, but resetting the spacing so that a +% period following counts as ending a sentence. (Idea found in latex.) +% +\edef\TeX{\TeX \spacefactor=1000 } + +% @LaTeX{} logo. Not quite the same results as the definition in +% latex.ltx, since we use a different font for the raised A; it's most +% convenient for us to use an explicitly smaller font, rather than using +% the \scriptstyle font (since we don't reset \scriptstyle and +% \scriptscriptstyle). +% +\def\LaTeX{% + L\kern-.36em + {\setbox0=\hbox{T}% + \vbox to \ht0{\hbox{% + \ifx\textnominalsize\xwordpt + % for 10pt running text, \lllsize (8pt) is too small for the A in LaTeX. + % Revert to plain's \scriptsize, which is 7pt. + \count255=\the\fam $\fam\count255 \scriptstyle A$% + \else + % For 11pt, we can use our lllsize. + \selectfonts\lllsize A% + \fi + }% + \vss + }}% + \kern-.15em + \TeX +} + +% Some math mode symbols. +\def\bullet{$\ptexbullet$} +\def\geq{\ifmmode \ge\else $\ge$\fi} +\def\leq{\ifmmode \le\else $\le$\fi} +\def\minus{\ifmmode -\else $-$\fi} + +% @dots{} outputs an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in the cm +% typewriter fonts as three actual period characters; on the other hand, +% in other typewriter fonts three periods are wider than 1.5em. So do +% whichever is larger. +% +\def\dots{% + \leavevmode + \setbox0=\hbox{...}% get width of three periods + \ifdim\wd0 > 1.5em + \dimen0 = \wd0 + \else + \dimen0 = 1.5em + \fi + \hbox to \dimen0{% + \hskip 0pt plus.25fil + .\hskip 0pt plus1fil + .\hskip 0pt plus1fil + .\hskip 0pt plus.5fil + }% +} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \dots + \spacefactor=\endofsentencespacefactor +} + +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. +% +% Since these characters are used in examples, they should be an even number of +% \tt widths. Each \tt character is 1en, so two makes it 1em. +% +\def\point{$\star$} +\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}} +\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} +\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}} +\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} +\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}} + +% The @error{} command. +% Adapted from the TeXbook's \boxit. +% +\newbox\errorbox +% +{\tentt \global\dimen0 = 3em}% Width of the box. +\dimen2 = .55pt % Thickness of rules +% The text. (`r' is open on the right, `e' somewhat less so on the left.) +\setbox0 = \hbox{\kern-.75pt \reducedsf \putworderror\kern-1.5pt} +% +\setbox\errorbox=\hbox to \dimen0{\hfil + \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. + \advance\hsize by -2\dimen2 % Rules. + \vbox{% + \hrule height\dimen2 + \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. + \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. + \kern3pt\vrule width\dimen2}% Space to right. + \hrule height\dimen2} + \hfil} +% +\def\error{\leavevmode\lower.7ex\copy\errorbox} + +% @pounds{} is a sterling sign, which Knuth put in the CM italic font. +% +\def\pounds{{\it\$}} + +% @euro{} comes from a separate font, depending on the current style. +% We use the free feym* fonts from the eurosym package by Henrik +% Theiling, which support regular, slanted, bold and bold slanted (and +% "outlined" (blackboard board, sort of) versions, which we don't need). +% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. +% +% Although only regular is the truly official Euro symbol, we ignore +% that. The Euro is designed to be slightly taller than the regular +% font height. +% +% feymr - regular +% feymo - slanted +% feybr - bold +% feybo - bold slanted +% +% There is no good (free) typewriter version, to my knowledge. +% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. +% Hmm. +% +% Also doesn't work in math. Do we need to do math with euro symbols? +% Hope not. +% +% +\def\euro{{\eurofont e}} +\def\eurofont{% + % We set the font at each command, rather than predefining it in + % \textfonts and the other font-switching commands, so that + % installations which never need the symbol don't have to have the + % font installed. + % + % There is only one designed size (nominal 10pt), so we always scale + % that to the current nominal size. + % + % By the way, simply using "at 1em" works for cmr10 and the like, but + % does not work for cmbx10 and other extended/shrunken fonts. + % + \def\eurosize{\csname\curfontsize nominalsize\endcsname}% + % + \ifx\curfontstyle\bfstylename + % bold: + \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize + \else + % regular: + \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize + \fi + \thiseurofont +} + +% Glyphs from the EC fonts. We don't use \let for the aliases, because +% sometimes we redefine the original macro, and the alias should reflect +% the redefinition. +% +% Use LaTeX names for the Icelandic letters. +\def\DH{{\ecfont \char"D0}} % Eth +\def\dh{{\ecfont \char"F0}} % eth +\def\TH{{\ecfont \char"DE}} % Thorn +\def\th{{\ecfont \char"FE}} % thorn +% +\def\guillemetleft{{\ecfont \char"13}} +\def\guillemotleft{\guillemetleft} +\def\guillemetright{{\ecfont \char"14}} +\def\guillemotright{\guillemetright} +\def\guilsinglleft{{\ecfont \char"0E}} +\def\guilsinglright{{\ecfont \char"0F}} +\def\quotedblbase{{\ecfont \char"12}} +\def\quotesinglbase{{\ecfont \char"0D}} +% +% This positioning is not perfect (see the ogonek LaTeX package), but +% we have the precomposed glyphs for the most common cases. We put the +% tests to use those glyphs in the single \ogonek macro so we have fewer +% dummy definitions to worry about for index entries, etc. +% +% ogonek is also used with other letters in Lithuanian (IOU), but using +% the precomposed glyphs for those is not so easy since they aren't in +% the same EC font. +\def\ogonek#1{{% + \def\temp{#1}% + \ifx\temp\macrocharA\Aogonek + \else\ifx\temp\macrochara\aogonek + \else\ifx\temp\macrocharE\Eogonek + \else\ifx\temp\macrochare\eogonek + \else + \ecfont \setbox0=\hbox{#1}% + \ifdim\ht0=1ex\accent"0C #1% + \else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}% + \fi + \fi\fi\fi\fi + }% +} +\def\Aogonek{{\ecfont \char"81}}\def\macrocharA{A} +\def\aogonek{{\ecfont \char"A1}}\def\macrochara{a} +\def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E} +\def\eogonek{{\ecfont \char"A6}}\def\macrochare{e} +% +% Use the ec* fonts (cm-super in outline format) for non-CM glyphs. +\def\ecfont{% + % We can't distinguish serif/sans and italic/slanted, but this + % is used for crude hacks anyway (like adding French and German + % quotes to documents typeset with CM, where we lose kerning), so + % hopefully nobody will notice/care. + \edef\ecsize{\csname\curfontsize ecsize\endcsname}% + \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}% + \ifmonospace + % typewriter: + \font\thisecfont = ectt\ecsize \space at \nominalsize + \else + \ifx\curfontstyle\bfstylename + % bold: + \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize + \else + % regular: + \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize + \fi + \fi + \thisecfont +} + +% @registeredsymbol - R in a circle. The font for the R should really +% be smaller yet, but lllsize is the best we can do for now. +% Adapted from the plain.tex definition of \copyright. +% +\def\registeredsymbol{% + $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% + \hfil\crcr\Orb}}% + }$% +} + +% @textdegree - the normal degrees sign. +% +\def\textdegree{$^\circ$} + +% Laurent Siebenmann reports \Orb undefined with: +% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 +% so we'll define it if necessary. +% +\ifx\Orb\thisisundefined +\def\Orb{\mathhexbox20D} +\fi + +% Quotes. +\chardef\quotedblleft="5C +\chardef\quotedblright=`\" +\chardef\quoteleft=`\` +\chardef\quoteright=`\' + + +\message{page headings,} + +\newskip\titlepagetopglue \titlepagetopglue = 1.5in +\newskip\titlepagebottomglue \titlepagebottomglue = 2pc + +% First the title page. Must do @settitle before @titlepage. +\newif\ifseenauthor +\newif\iffinishedtitlepage + +% Do an implicit @contents or @shortcontents after @end titlepage if the +% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. +% +\newif\ifsetcontentsaftertitlepage + \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue +\newif\ifsetshortcontentsaftertitlepage + \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue + +\parseargdef\shorttitlepage{% + \begingroup \hbox{}\vskip 1.5in \chaprm \centerline{#1}% + \endgroup\page\hbox{}\page} + +\envdef\titlepage{% + % Open one extra group, as we want to close it in the middle of \Etitlepage. + \begingroup + \parindent=0pt \textfonts + % Leave some space at the very top of the page. + \vglue\titlepagetopglue + % No rule at page bottom unless we print one at the top with @title. + \finishedtitlepagetrue + % + % Most title ``pages'' are actually two pages long, with space + % at the top of the second. We don't want the ragged left on the second. + \let\oldpage = \page + \def\page{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + \let\page = \oldpage + \page + \null + }% +} + +\def\Etitlepage{% + \iffinishedtitlepage\else + \finishtitlepage + \fi + % It is important to do the page break before ending the group, + % because the headline and footline are only empty inside the group. + % If we use the new definition of \page, we always get a blank page + % after the title page, which we certainly don't want. + \oldpage + \endgroup + % + % Need this before the \...aftertitlepage checks so that if they are + % in effect the toc pages will come out with page numbers. + \HEADINGSon + % + % If they want short, they certainly want long too. + \ifsetshortcontentsaftertitlepage + \shortcontents + \contents + \global\let\shortcontents = \relax + \global\let\contents = \relax + \fi + % + \ifsetcontentsaftertitlepage + \contents + \global\let\contents = \relax + \global\let\shortcontents = \relax + \fi +} + +\def\finishtitlepage{% + \vskip4pt \hrule height 2pt width \hsize + \vskip\titlepagebottomglue + \finishedtitlepagetrue +} + +% Settings used for typesetting titles: no hyphenation, no indentation, +% don't worry much about spacing, ragged right. This should be used +% inside a \vbox, and fonts need to be set appropriately first. Because +% it is always used for titles, nothing else, we call \rmisbold. \par +% should be specified before the end of the \vbox, since a vbox is a group. +% +\def\raggedtitlesettings{% + \rmisbold + \hyphenpenalty=10000 + \parindent=0pt + \tolerance=5000 + \ptexraggedright +} + +% Macros to be used within @titlepage: + +\let\subtitlerm=\tenrm +\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} + +\parseargdef\title{% + \checkenv\titlepage + \vbox{\titlefonts \raggedtitlesettings #1\par}% + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt +} + +\parseargdef\subtitle{% + \checkenv\titlepage + {\subtitlefont \rightline{#1}}% +} + +% @author should come last, but may come many times. +% It can also be used inside @quotation. +% +\parseargdef\author{% + \def\temp{\quotation}% + \ifx\thisenv\temp + \def\quotationauthor{#1}% printed in \Equotation. + \else + \checkenv\titlepage + \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi + {\secfonts\rmisbold \leftline{#1}}% + \fi +} + + +% Set up page headings and footings. + +\let\thispage=\folio + +\newtoks\evenheadline % headline on even pages +\newtoks\oddheadline % headline on odd pages +\newtoks\evenfootline % footline on even pages +\newtoks\oddfootline % footline on odd pages + +% Now make TeX use those variables +\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline + \else \the\evenheadline \fi}} +\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline + \else \the\evenfootline \fi}\HEADINGShook} +\let\HEADINGShook=\relax + +% Commands to set those variables. +% For example, this is what @headings on does +% @evenheading @thistitle|@thispage|@thischapter +% @oddheading @thischapter|@thispage|@thistitle +% @evenfooting @thisfile|| +% @oddfooting ||@thisfile + + +\def\evenheading{\parsearg\evenheadingxxx} +\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} +\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% +\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\def\oddheading{\parsearg\oddheadingxxx} +\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} +\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% +\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% + +\def\evenfooting{\parsearg\evenfootingxxx} +\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} +\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% +\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + +\def\oddfooting{\parsearg\oddfootingxxx} +\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} +\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% + \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% + % + % Leave some space for the footline. Hopefully ok to assume + % @evenfooting will not be used by itself. + \global\advance\pageheight by -12pt + \global\advance\vsize by -12pt +} + +\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} + +% @evenheadingmarks top \thischapter <- chapter at the top of a page +% @evenheadingmarks bottom \thischapter <- chapter at the bottom of a page +% +% The same set of arguments for: +% +% @oddheadingmarks +% @evenfootingmarks +% @oddfootingmarks +% @everyheadingmarks +% @everyfootingmarks + +\def\evenheadingmarks{\headingmarks{even}{heading}} +\def\oddheadingmarks{\headingmarks{odd}{heading}} +\def\evenfootingmarks{\headingmarks{even}{footing}} +\def\oddfootingmarks{\headingmarks{odd}{footing}} +\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1} + \headingmarks{odd}{heading}{#1} } +\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1} + \headingmarks{odd}{footing}{#1} } +% #1 = even/odd, #2 = heading/footing, #3 = top/bottom. +\def\headingmarks#1#2#3 {% + \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname + \global\expandafter\let\csname get#1#2marks\endcsname \temp +} + +\everyheadingmarks bottom +\everyfootingmarks bottom + +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. +% @headings singleafter turns on single-sided headings after this page. +% By default, they are off at the start of a document, +% and turned `on' after @end titlepage. + +\def\headings #1 {\csname HEADINGS#1\endcsname} + +\def\headingsoff{% non-global headings elimination + \evenheadline={\hfil}\evenfootline={\hfil}% + \oddheadline={\hfil}\oddfootline={\hfil}% +} + +\def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting +\HEADINGSoff % it's the default + +% When we turn headings on, set the page number to 1. +% For double-sided printing, put current file name in lower left corner, +% chapter name on inside top of right hand pages, document +% title on inside top of left hand pages, and page numbers on outside top +% edge of all pages. +\def\HEADINGSdouble{% +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} +\let\contentsalignmacro = \chappager + +% For single-sided printing, chapter title goes across top left of page, +% page number on top right. +\def\HEADINGSsingle{% +\global\pageno=1 +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} +\def\HEADINGSon{\HEADINGSdouble} + +\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} +\let\HEADINGSdoubleafter=\HEADINGSafter +\def\HEADINGSdoublex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\folio\hfil\thistitle}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage +} + +\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} +\def\HEADINGSsinglex{% +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} + +% Subroutines used in generating headings +% This produces Day Month Year style of output. +% Only define if not already defined, in case a txi-??.tex file has set +% up a different format (e.g., txi-cs.tex does this). +\ifx\today\thisisundefined +\def\today{% + \number\day\space + \ifcase\month + \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr + \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug + \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec + \fi + \space\number\year} +\fi + +% @settitle line... specifies the title of the document, for headings. +% It generates no output of its own. +\def\thistitle{\putwordNoTitle} +\def\settitle{\parsearg{\gdef\thistitle}} + + +\message{tables,} +% Tables -- @table, @ftable, @vtable, @item(x). + +% default indentation of table text +\newdimen\tableindent \tableindent=.8in +% default indentation of @itemize and @enumerate text +\newdimen\itemindent \itemindent=.3in +% margin between end of table item and start of table text. +\newdimen\itemmargin \itemmargin=.1in + +% used internally for \itemindent minus \itemmargin +\newdimen\itemmax + +% Note @table, @ftable, and @vtable define @item, @itemx, etc., with +% these defs. +% They also define \itemindex +% to index the item name in whatever manner is desired (perhaps none). + +\newif\ifitemxneedsnegativevskip + +\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} + +\def\internalBitem{\smallbreak \parsearg\itemzzz} +\def\internalBitemx{\itemxpar \parsearg\itemzzz} + +\def\itemzzz #1{\begingroup % + \advance\hsize by -\rightskip + \advance\hsize by -\tableindent + \setbox0=\hbox{\itemindicate{#1}}% + \itemindex{#1}% + \nobreak % This prevents a break before @itemx. + % + % If the item text does not fit in the space we have, put it on a line + % by itself, and do not allow a page break either before or after that + % line. We do not start a paragraph here because then if the next + % command is, e.g., @kindex, the whatsit would get put into the + % horizontal list on a line by itself, resulting in extra blank space. + \ifdim \wd0>\itemmax + % + % Make this a paragraph so we get the \parskip glue and wrapping, + % but leave it ragged-right. + \begingroup + \advance\leftskip by-\tableindent + \advance\hsize by\tableindent + \advance\rightskip by0pt plus1fil\relax + \leavevmode\unhbox0\par + \endgroup + % + % We're going to be starting a paragraph, but we don't want the + % \parskip glue -- logically it's part of the @item we just started. + \nobreak \vskip-\parskip + % + % Stop a page break at the \parskip glue coming up. However, if + % what follows is an environment such as @example, there will be no + % \parskip glue; then the negative vskip we just inserted would + % cause the example and the item to crash together. So we use this + % bizarre value of 10001 as a signal to \aboveenvbreak to insert + % \parskip glue after all. Section titles are handled this way also. + % + \penalty 10001 + \endgroup + \itemxneedsnegativevskipfalse + \else + % The item text fits into the space. Start a paragraph, so that the + % following text (if any) will end up on the same line. + \noindent + % Do this with kerns and \unhbox so that if there is a footnote in + % the item text, it can migrate to the main vertical list and + % eventually be printed. + \nobreak\kern-\tableindent + \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 + \unhbox0 + \nobreak\kern\dimen0 + \endgroup + \itemxneedsnegativevskiptrue + \fi +} + +\def\item{\errmessage{@item while not in a list environment}} +\def\itemx{\errmessage{@itemx while not in a list environment}} + +% @table, @ftable, @vtable. +\envdef\table{% + \let\itemindex\gobble + \tablecheck{table}% +} +\envdef\ftable{% + \def\itemindex ##1{\doind {fn}{\code{##1}}}% + \tablecheck{ftable}% +} +\envdef\vtable{% + \def\itemindex ##1{\doind {vr}{\code{##1}}}% + \tablecheck{vtable}% +} +\def\tablecheck#1{% + \ifnum \the\catcode`\^^M=\active + \endgroup + \errmessage{This command won't work in this context; perhaps the problem is + that we are \inenvironment\thisenv}% + \def\next{\doignore{#1}}% + \else + \let\next\tablex + \fi + \next +} +\def\tablex#1{% + \def\itemindicate{#1}% + \parsearg\tabley +} +\def\tabley#1{% + {% + \makevalueexpandable + \edef\temp{\noexpand\tablez #1\space\space\space}% + \expandafter + }\temp \endtablez +} +\def\tablez #1 #2 #3 #4\endtablez{% + \aboveenvbreak + \ifnum 0#1>0 \advance \leftskip by #1\mil \fi + \ifnum 0#2>0 \tableindent=#2\mil \fi + \ifnum 0#3>0 \advance \rightskip by #3\mil \fi + \itemmax=\tableindent + \advance \itemmax by -\itemmargin + \advance \leftskip by \tableindent + \exdentamount=\tableindent + \parindent = 0pt + \parskip = \smallskipamount + \ifdim \parskip=0pt \parskip=2pt \fi + \let\item = \internalBitem + \let\itemx = \internalBitemx +} +\def\Etable{\endgraf\afterenvbreak} +\let\Eftable\Etable +\let\Evtable\Etable +\let\Eitemize\Etable +\let\Eenumerate\Etable + +% This is the counter used by @enumerate, which is really @itemize + +\newcount \itemno + +\envdef\itemize{\parsearg\doitemize} + +\def\doitemize#1{% + \aboveenvbreak + \itemmax=\itemindent + \advance\itemmax by -\itemmargin + \advance\leftskip by \itemindent + \exdentamount=\itemindent + \parindent=0pt + \parskip=\smallskipamount + \ifdim\parskip=0pt \parskip=2pt \fi + % + % Try typesetting the item mark that if the document erroneously says + % something like @itemize @samp (intending @table), there's an error + % right away at the @itemize. It's not the best error message in the + % world, but it's better than leaving it to the @item. This means if + % the user wants an empty mark, they have to say @w{} not just @w. + \def\itemcontents{#1}% + \setbox0 = \hbox{\itemcontents}% + % + % @itemize with no arg is equivalent to @itemize @bullet. + \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi + % + \let\item=\itemizeitem +} + +% Definition of @item while inside @itemize and @enumerate. +% +\def\itemizeitem{% + \advance\itemno by 1 % for enumerations + {\let\par=\endgraf \smallbreak}% reasonable place to break + {% + % If the document has an @itemize directly after a section title, a + % \nobreak will be last on the list, and \sectionheading will have + % done a \vskip-\parskip. In that case, we don't want to zero + % parskip, or the item text will crash with the heading. On the + % other hand, when there is normal text preceding the item (as there + % usually is), we do want to zero parskip, or there would be too much + % space. In that case, we won't have a \nobreak before. At least + % that's the theory. + \ifnum\lastpenalty<10000 \parskip=0in \fi + \noindent + \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% + % + \vadjust{\penalty 1200}}% not good to break after first line of item. + \flushcr +} + +% \splitoff TOKENS\endmark defines \first to be the first token in +% TOKENS, and \rest to be the remainder. +% +\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% + +% Allow an optional argument of an uppercase letter, lowercase letter, +% or number, to specify the first label in the enumerated list. No +% argument is the same as `1'. +% +\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} +\def\enumeratey #1 #2\endenumeratey{% + % If we were given no argument, pretend we were given `1'. + \def\thearg{#1}% + \ifx\thearg\empty \def\thearg{1}\fi + % + % Detect if the argument is a single token. If so, it might be a + % letter. Otherwise, the only valid thing it can be is a number. + % (We will always have one token, because of the test we just made. + % This is a good thing, since \splitoff doesn't work given nothing at + % all -- the first parameter is undelimited.) + \expandafter\splitoff\thearg\endmark + \ifx\rest\empty + % Only one token in the argument. It could still be anything. + % A ``lowercase letter'' is one whose \lccode is nonzero. + % An ``uppercase letter'' is one whose \lccode is both nonzero, and + % not equal to itself. + % Otherwise, we assume it's a number. + % + % We need the \relax at the end of the \ifnum lines to stop TeX from + % continuing to look for a . + % + \ifnum\lccode\expandafter`\thearg=0\relax + \numericenumerate % a number (we hope) + \else + % It's a letter. + \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax + \lowercaseenumerate % lowercase letter + \else + \uppercaseenumerate % uppercase letter + \fi + \fi + \else + % Multiple tokens in the argument. We hope it's a number. + \numericenumerate + \fi +} + +% An @enumerate whose labels are integers. The starting integer is +% given in \thearg. +% +\def\numericenumerate{% + \itemno = \thearg + \startenumeration{\the\itemno}% +} + +% The starting (lowercase) letter is in \thearg. +\def\lowercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more lowercase letters in @enumerate; get a bigger + alphabet}% + \fi + \char\lccode\itemno + }% +} + +% The starting (uppercase) letter is in \thearg. +\def\uppercaseenumerate{% + \itemno = \expandafter`\thearg + \startenumeration{% + % Be sure we're not beyond the end of the alphabet. + \ifnum\itemno=0 + \errmessage{No more uppercase letters in @enumerate; get a bigger + alphabet} + \fi + \char\uccode\itemno + }% +} + +% Call \doitemize, adding a period to the first argument and supplying the +% common last two arguments. Also subtract one from the initial value in +% \itemno, since @item increments \itemno. +% +\def\startenumeration#1{% + \advance\itemno by -1 + \doitemize{#1.}\flushcr +} + +% @alphaenumerate and @capsenumerate are abbreviations for giving an arg +% to @enumerate. +% +\def\alphaenumerate{\enumerate{a}} +\def\capsenumerate{\enumerate{A}} +\def\Ealphaenumerate{\Eenumerate} +\def\Ecapsenumerate{\Eenumerate} + + +% @multitable macros +% Amy Hendrickson, 8/18/94, 3/6/96 +% +% @multitable ... @end multitable will make as many columns as desired. +% Contents of each column will wrap at width given in preamble. Width +% can be specified either with sample text given in a template line, +% or in percent of \hsize, the current width of text on page. + +% Table can continue over pages but will only break between lines. + +% To make preamble: +% +% Either define widths of columns in terms of percent of \hsize: +% @multitable @columnfractions .25 .3 .45 +% @item ... +% +% Numbers following @columnfractions are the percent of the total +% current hsize to be used for each column. You may use as many +% columns as desired. + + +% Or use a template: +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item ... +% using the widest term desired in each column. + +% Each new table line starts with @item, each subsequent new column +% starts with @tab. Empty columns may be produced by supplying @tab's +% with nothing between them for as many times as empty columns are needed, +% ie, @tab@tab@tab will produce two empty columns. + +% @item, @tab do not need to be on their own lines, but it will not hurt +% if they are. + +% Sample multitable: + +% @multitable {Column 1 template} {Column 2 template} {Column 3 template} +% @item first col stuff @tab second col stuff @tab third col +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff +% @tab Many paragraphs of text may be used in any column. +% +% They will wrap at the width determined by the template. +% @item@tab@tab This will be in third column. +% @end multitable + +% Default dimensions may be reset by user. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items, baseline +% to baseline. +% 0pt means it depends on current normal line spacing. +% +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt + +% Macros used to set up halign preamble: +% +\let\endsetuptable\relax +\def\xendsetuptable{\endsetuptable} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} +\newif\ifsetpercent + +% #1 is the @columnfraction, usually a decimal number like .5, but might +% be just 1. We just use it, whatever it is. +% +\def\pickupwholefraction#1 {% + \global\advance\colcount by 1 + \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% + \setuptable +} + +\newcount\colcount +\def\setuptable#1{% + \def\firstarg{#1}% + \ifx\firstarg\xendsetuptable + \let\go = \relax + \else + \ifx\firstarg\xcolumnfractions + \global\setpercenttrue + \else + \ifsetpercent + \let\go\pickupwholefraction + \else + \global\advance\colcount by 1 + \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a + % separator; typically that is always in the input, anyway. + \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% + \fi + \fi + \ifx\go\pickupwholefraction + % Put the argument back for the \pickupwholefraction call, so + % we'll always have a period there to be parsed. + \def\go{\pickupwholefraction#1}% + \else + \let\go = \setuptable + \fi% + \fi + \go +} + +% multitable-only commands. +% +% @headitem starts a heading row, which we typeset in bold. +% Assignments have to be global since we are inside the implicit group +% of an alignment entry. \everycr resets \everytab so we don't have to +% undo it ourselves. +\def\headitemfont{\b}% for people to use in the template row; not changeable +\def\headitem{% + \checkenv\multitable + \crcr + \global\everytab={\bf}% can't use \headitemfont since the parsing differs + \the\everytab % for the first item +}% +% +% A \tab used to include \hskip1sp. But then the space in a template +% line is not enough. That is bad. So let's go back to just `&' until +% we again encounter the problem the 1sp was intended to solve. +% --karl, nathan@acm.org, 20apr99. +\def\tab{\checkenv\multitable &\the\everytab}% + +% @multitable ... @end multitable definitions: +% +\newtoks\everytab % insert after every tab. +% +\envdef\multitable{% + \vskip\parskip + \startsavinginserts + % + % @item within a multitable starts a normal row. + % We use \def instead of \let so that if one of the multitable entries + % contains an @itemize, we don't choke on the \item (seen as \crcr aka + % \endtemplate) expanding \doitemize. + \def\item{\crcr}% + % + \tolerance=9500 + \hbadness=9500 + \setmultitablespacing + \parskip=\multitableparskip + \parindent=\multitableparindent + \overfullrule=0pt + \global\colcount=0 + % + \everycr = {% + \noalign{% + \global\everytab={}% + \global\colcount=0 % Reset the column counter. + % Check for saved footnotes, etc. + \checkinserts + % Keeps underfull box messages off when table breaks over pages. + %\filbreak + % Maybe so, but it also creates really weird page breaks when the + % table breaks over pages. Wouldn't \vfil be better? Wait until the + % problem manifests itself, so it can be fixed for real --karl. + }% + }% + % + \parsearg\domultitable +} +\def\domultitable#1{% + % To parse everything between @multitable and @item: + \setuptable#1 \endsetuptable + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. + \halign\bgroup &% + \global\advance\colcount by 1 + \multistrut + \vtop{% + % Use the current \colcount to find the correct column width: + \hsize=\expandafter\csname col\the\colcount\endcsname + % + % In order to keep entries from bumping into each other + % we will add a \leftskip of \multitablecolspace to all columns after + % the first one. + % + % If a template has been used, we will add \multitablecolspace + % to the width of each template entry. + % + % If the user has set preamble in terms of percent of \hsize we will + % use that dimension as the width of the column, and the \leftskip + % will keep entries from bumping into each other. Table will start at + % left margin and final column will justify at right margin. + % + % Make sure we don't inherit \rightskip from the outer environment. + \rightskip=0pt + \ifnum\colcount=1 + % The first column will be indented with the surrounding text. + \advance\hsize by\leftskip + \else + \ifsetpercent \else + % If user has not set preamble in terms of percent of \hsize + % we will advance \hsize by \multitablecolspace. + \advance\hsize by \multitablecolspace + \fi + % In either case we will make \leftskip=\multitablecolspace: + \leftskip=\multitablecolspace + \fi + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively + % marking characters. + \noindent\ignorespaces##\unskip\multistrut + }\cr +} +\def\Emultitable{% + \crcr + \egroup % end the \halign + \global\setpercentfalse +} + +\def\setmultitablespacing{% + \def\multistrut{\strut}% just use the standard line spacing + % + % Compute \multitablelinespace (if not defined by user) for use in + % \multitableparskip calculation. We used define \multistrut based on + % this, but (ironically) that caused the spacing to be off. + % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. +\ifdim\multitablelinespace=0pt +\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip +\global\advance\multitablelinespace by-\ht0 +\fi +% Test to see if parskip is larger than space between lines of +% table. If not, do nothing. +% If so, set to same dimension as multitablelinespace. +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller + % than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller + % than skip between lines in the table. +\fi} + + +\message{conditionals,} + +% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, +% @ifnotxml always succeed. They currently do nothing; we don't +% attempt to check whether the conditionals are properly nested. But we +% have to remember that they are conditionals, so that @end doesn't +% attempt to close an environment group. +% +\def\makecond#1{% + \expandafter\let\csname #1\endcsname = \relax + \expandafter\let\csname iscond.#1\endcsname = 1 +} +\makecond{iftex} +\makecond{ifnotdocbook} +\makecond{ifnothtml} +\makecond{ifnotinfo} +\makecond{ifnotplaintext} +\makecond{ifnotxml} + +% Ignore @ignore, @ifhtml, @ifinfo, and the like. +% +\def\direntry{\doignore{direntry}} +\def\documentdescription{\doignore{documentdescription}} +\def\docbook{\doignore{docbook}} +\def\html{\doignore{html}} +\def\ifdocbook{\doignore{ifdocbook}} +\def\ifhtml{\doignore{ifhtml}} +\def\ifinfo{\doignore{ifinfo}} +\def\ifnottex{\doignore{ifnottex}} +\def\ifplaintext{\doignore{ifplaintext}} +\def\ifxml{\doignore{ifxml}} +\def\ignore{\doignore{ignore}} +\def\menu{\doignore{menu}} +\def\xml{\doignore{xml}} + +% Ignore text until a line `@end #1', keeping track of nested conditionals. +% +% A count to remember the depth of nesting. +\newcount\doignorecount + +\def\doignore#1{\begingroup + % Scan in ``verbatim'' mode: + \obeylines + \catcode`\@ = \other + \catcode`\{ = \other + \catcode`\} = \other + % + % Make sure that spaces turn into tokens that match what \doignoretext wants. + \spaceisspace + % + % Count number of #1's that we've seen. + \doignorecount = 0 + % + % Swallow text until we reach the matching `@end #1'. + \dodoignore{#1}% +} + +{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. + \obeylines % + % + \gdef\dodoignore#1{% + % #1 contains the command name as a string, e.g., `ifinfo'. + % + % Define a command to find the next `@end #1'. + \long\def\doignoretext##1^^M@end #1{% + \doignoretextyyy##1^^M@#1\_STOP_}% + % + % And this command to find another #1 command, at the beginning of a + % line. (Otherwise, we would consider a line `@c @ifset', for + % example, to count as an @ifset for nesting.) + \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% + % + % And now expand that command. + \doignoretext ^^M% + }% +} + +\def\doignoreyyy#1{% + \def\temp{#1}% + \ifx\temp\empty % Nothing found. + \let\next\doignoretextzzz + \else % Found a nested condition, ... + \advance\doignorecount by 1 + \let\next\doignoretextyyy % ..., look for another. + % If we're here, #1 ends with ^^M\ifinfo (for example). + \fi + \next #1% the token \_STOP_ is present just after this macro. +} + +% We have to swallow the remaining "\_STOP_". +% +\def\doignoretextzzz#1{% + \ifnum\doignorecount = 0 % We have just found the outermost @end. + \let\next\enddoignore + \else % Still inside a nested condition. + \advance\doignorecount by -1 + \let\next\doignoretext % Look for the next @end. + \fi + \next +} + +% Finish off ignored text. +{ \obeylines% + % Ignore anything after the last `@end #1'; this matters in verbatim + % environments, where otherwise the newline after an ignored conditional + % would result in a blank line in the output. + \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% +} + + +% @set VAR sets the variable VAR to an empty value. +% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. +% +% Since we want to separate VAR from REST-OF-LINE (which might be +% empty), we can't just use \parsearg; we have to insert a space of our +% own to delimit the rest of the line, and then take it out again if we +% didn't need it. +% We rely on the fact that \parsearg sets \catcode`\ =10. +% +\parseargdef\set{\setyyy#1 \endsetyyy} +\def\setyyy#1 #2\endsetyyy{% + {% + \makevalueexpandable + \def\temp{#2}% + \edef\next{\gdef\makecsname{SET#1}}% + \ifx\temp\empty + \next{}% + \else + \setzzz#2\endsetzzz + \fi + }% +} +% Remove the trailing space \setxxx inserted. +\def\setzzz#1 \endsetzzz{\next{#1}} + +% @clear VAR clears (i.e., unsets) the variable VAR. +% +\parseargdef\clear{% + {% + \makevalueexpandable + \global\expandafter\let\csname SET#1\endcsname=\relax + }% +} + +% @value{foo} gets the text saved in variable foo. +\def\value{\begingroup\makevalueexpandable\valuexxx} +\def\valuexxx#1{\expandablevalue{#1}\endgroup} +{ + \catcode`\- = \active \catcode`\_ = \active + % + \gdef\makevalueexpandable{% + \let\value = \expandablevalue + % We don't want these characters active, ... + \catcode`\-=\other \catcode`\_=\other + % ..., but we might end up with active ones in the argument if + % we're called from @code, as @code{@value{foo-bar_}}, though. + % So \let them to their normal equivalents. + \let-\normaldash \let_\normalunderscore + } +} + +% We have this subroutine so that we can handle at least some @value's +% properly in indexes (we call \makevalueexpandable in \indexdummies). +% The command has to be fully expandable (if the variable is set), since +% the result winds up in the index file. This means that if the +% variable's value contains other Texinfo commands, it's almost certain +% it will fail (although perhaps we could fix that with sufficient work +% to do a one-level expansion on the result, instead of complete). +% +\def\expandablevalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {[No value for ``#1'']}% + \message{Variable `#1', used in @value, is not set.}% + \else + \csname SET#1\endcsname + \fi +} + +% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined +% with @set. +% +% To get special treatment of `@end ifset,' call \makeond and the redefine. +% +\makecond{ifset} +\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} +\def\doifset#1#2{% + {% + \makevalueexpandable + \let\next=\empty + \expandafter\ifx\csname SET#2\endcsname\relax + #1% If not set, redefine \next. + \fi + \expandafter + }\next +} +\def\ifsetfail{\doignore{ifset}} + +% @ifclear VAR ... @end executes the `...' iff VAR has never been +% defined with @set, or has been undefined with @clear. +% +% The `\else' inside the `\doifset' parameter is a trick to reuse the +% above code: if the variable is not set, do nothing, if it is set, +% then redefine \next to \ifclearfail. +% +\makecond{ifclear} +\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} +\def\ifclearfail{\doignore{ifclear}} + +% @ifcommandisdefined CMD ... @end executes the `...' if CMD (written +% without the @) is in fact defined. We can only feasibly check at the +% TeX level, so something like `mathcode' is going to considered +% defined even though it is not a Texinfo command. +% +\makecond{ifcommanddefined} +\def\ifcommanddefined{\parsearg{\doifcmddefined{\let\next=\ifcmddefinedfail}}} +% +\def\doifcmddefined#1#2{{% + \makevalueexpandable + \let\next=\empty + \expandafter\ifx\csname #2\endcsname\relax + #1% If not defined, \let\next as above. + \fi + \expandafter + }\next +} +\def\ifcmddefinedfail{\doignore{ifcommanddefined}} + +% @ifcommandnotdefined CMD ... handled similar to @ifclear above. +\makecond{ifcommandnotdefined} +\def\ifcommandnotdefined{% + \parsearg{\doifcmddefined{\else \let\next=\ifcmdnotdefinedfail}}} +\def\ifcmdnotdefinedfail{\doignore{ifcommandnotdefined}} + +% Set the `txicommandconditionals' variable, so documents have a way to +% test if the @ifcommand...defined conditionals are available. +\set txicommandconditionals + +% @dircategory CATEGORY -- specify a category of the dir file +% which this file should belong to. Ignore this in TeX. +\let\dircategory=\comment + +% @defininfoenclose. +\let\definfoenclose=\comment + + +\message{indexing,} +% Index generation facilities + +% Define \newwrite to be identical to plain tex's \newwrite +% except not \outer, so it can be used within macros and \if's. +\edef\newwrite{\makecsname{ptexnewwrite}} + +% \newindex {foo} defines an index named foo. +% It automatically defines \fooindex such that +% \fooindex ...rest of line... puts an entry in the index foo. +% It also defines \fooindfile to be the number of the output channel for +% the file that accumulates this index. The file's extension is foo. +% The name of an index should be no more than 2 characters long +% for the sake of vms. +% +\def\newindex#1{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 % Open the file + \fi + \expandafter\xdef\csname#1index\endcsname{% % Define @#1index + \noexpand\doindex{#1}} +} + +% @defindex foo == \newindex{foo} +% +\def\defindex{\parsearg\newindex} + +% Define @defcodeindex, like @defindex except put all entries in @code. +% +\def\defcodeindex{\parsearg\newcodeindex} +% +\def\newcodeindex#1{% + \iflinks + \expandafter\newwrite \csname#1indfile\endcsname + \openout \csname#1indfile\endcsname \jobname.#1 + \fi + \expandafter\xdef\csname#1index\endcsname{% + \noexpand\docodeindex{#1}}% +} + + +% @synindex foo bar makes index foo feed into index bar. +% Do this instead of @defindex foo if you don't want it as a separate index. +% +% @syncodeindex foo bar similar, but put all entries made for index foo +% inside @code. +% +\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} +\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} + +% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), +% #3 the target index (bar). +\def\dosynindex#1#2#3{% + % Only do \closeout if we haven't already done it, else we'll end up + % closing the target index. + \expandafter \ifx\csname donesynindex#2\endcsname \relax + % The \closeout helps reduce unnecessary open files; the limit on the + % Acorn RISC OS is a mere 16 files. + \expandafter\closeout\csname#2indfile\endcsname + \expandafter\let\csname donesynindex#2\endcsname = 1 + \fi + % redefine \fooindfile: + \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname + \expandafter\let\csname#2indfile\endcsname=\temp + % redefine \fooindex: + \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% +} + +% Define \doindex, the driver for all \fooindex macros. +% Argument #1 is generated by the calling \fooindex macro, +% and it is "foo", the name of the index. + +% \doindex just uses \parsearg; it calls \doind for the actual work. +% This is because \doind is more useful to call from other macros. + +% There is also \dosubind {index}{topic}{subtopic} +% which makes an entry in a two-level index such as the operation index. + +\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\doind{\indexname}{#1}} + +% like the previous two, but they put @code around the argument. +\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} +\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} + +% Take care of Texinfo commands that can appear in an index entry. +% Since there are some commands we want to expand, and others we don't, +% we have to laboriously prevent expansion for those that we don't. +% +\def\indexdummies{% + \escapechar = `\\ % use backslash in output files. + \def\@{@}% change to @@ when we switch to @ as escape char in index files. + \def\ {\realbackslash\space }% + % + % Need these unexpandable (because we define \tt as a dummy) + % definitions when @{ or @} appear in index entry text. Also, more + % complicated, when \tex is in effect and \{ is a \delimiter again. + % We can't use \lbracecmd and \rbracecmd because texindex assumes + % braces and backslashes are used only as delimiters. Perhaps we + % should define @lbrace and @rbrace commands a la @comma. + \def\{{{\tt\char123}}% + \def\}{{\tt\char125}}% + % + % I don't entirely understand this, but when an index entry is + % generated from a macro call, the \endinput which \scanmacro inserts + % causes processing to be prematurely terminated. This is, + % apparently, because \indexsorttmp is fully expanded, and \endinput + % is an expandable command. The redefinition below makes \endinput + % disappear altogether for that purpose -- although logging shows that + % processing continues to some further point. On the other hand, it + % seems \endinput does not hurt in the printed index arg, since that + % is still getting written without apparent harm. + % + % Sample source (mac-idx3.tex, reported by Graham Percival to + % help-texinfo, 22may06): + % @macro funindex {WORD} + % @findex xyz + % @end macro + % ... + % @funindex commtest + % + % The above is not enough to reproduce the bug, but it gives the flavor. + % + % Sample whatsit resulting: + % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} + % + % So: + \let\endinput = \empty + % + % Do the redefinitions. + \commondummies +} + +% For the aux and toc files, @ is the escape character. So we want to +% redefine everything using @ as the escape character (instead of +% \realbackslash, still used for index files). When everything uses @, +% this will be simpler. +% +\def\atdummies{% + \def\@{@@}% + \def\ {@ }% + \let\{ = \lbraceatcmd + \let\} = \rbraceatcmd + % + % Do the redefinitions. + \commondummies + \otherbackslash +} + +% Called from \indexdummies and \atdummies. +% +\def\commondummies{% + % + % \definedummyword defines \#1 as \string\#1\space, thus effectively + % preventing its expansion. This is used only for control words, + % not control letters, because the \space would be incorrect for + % control characters, but is needed to separate the control word + % from whatever follows. + % + % For control letters, we have \definedummyletter, which omits the + % space. + % + % These can be used both for control words that take an argument and + % those that do not. If it is followed by {arg} in the input, then + % that will dutifully get written to the index (or wherever). + % + \def\definedummyword ##1{\def##1{\string##1\space}}% + \def\definedummyletter##1{\def##1{\string##1}}% + \let\definedummyaccent\definedummyletter + % + \commondummiesnofonts + % + \definedummyletter\_% + \definedummyletter\-% + % + % Non-English letters. + \definedummyword\AA + \definedummyword\AE + \definedummyword\DH + \definedummyword\L + \definedummyword\O + \definedummyword\OE + \definedummyword\TH + \definedummyword\aa + \definedummyword\ae + \definedummyword\dh + \definedummyword\exclamdown + \definedummyword\l + \definedummyword\o + \definedummyword\oe + \definedummyword\ordf + \definedummyword\ordm + \definedummyword\questiondown + \definedummyword\ss + \definedummyword\th + % + % Although these internal commands shouldn't show up, sometimes they do. + \definedummyword\bf + \definedummyword\gtr + \definedummyword\hat + \definedummyword\less + \definedummyword\sf + \definedummyword\sl + \definedummyword\tclose + \definedummyword\tt + % + \definedummyword\LaTeX + \definedummyword\TeX + % + % Assorted special characters. + \definedummyword\arrow + \definedummyword\bullet + \definedummyword\comma + \definedummyword\copyright + \definedummyword\registeredsymbol + \definedummyword\dots + \definedummyword\enddots + \definedummyword\entrybreak + \definedummyword\equiv + \definedummyword\error + \definedummyword\euro + \definedummyword\expansion + \definedummyword\geq + \definedummyword\guillemetleft + \definedummyword\guillemetright + \definedummyword\guilsinglleft + \definedummyword\guilsinglright + \definedummyword\lbracechar + \definedummyword\leq + \definedummyword\minus + \definedummyword\ogonek + \definedummyword\pounds + \definedummyword\point + \definedummyword\print + \definedummyword\quotedblbase + \definedummyword\quotedblleft + \definedummyword\quotedblright + \definedummyword\quoteleft + \definedummyword\quoteright + \definedummyword\quotesinglbase + \definedummyword\rbracechar + \definedummyword\result + \definedummyword\textdegree + % + % We want to disable all macros so that they are not expanded by \write. + \macrolist + % + \normalturnoffactive + % + % Handle some cases of @value -- where it does not contain any + % (non-fully-expandable) commands. + \makevalueexpandable +} + +% \commondummiesnofonts: common to \commondummies and \indexnofonts. +% +\def\commondummiesnofonts{% + % Control letters and accents. + \definedummyletter\!% + \definedummyaccent\"% + \definedummyaccent\'% + \definedummyletter\*% + \definedummyaccent\,% + \definedummyletter\.% + \definedummyletter\/% + \definedummyletter\:% + \definedummyaccent\=% + \definedummyletter\?% + \definedummyaccent\^% + \definedummyaccent\`% + \definedummyaccent\~% + \definedummyword\u + \definedummyword\v + \definedummyword\H + \definedummyword\dotaccent + \definedummyword\ogonek + \definedummyword\ringaccent + \definedummyword\tieaccent + \definedummyword\ubaraccent + \definedummyword\udotaccent + \definedummyword\dotless + % + % Texinfo font commands. + \definedummyword\b + \definedummyword\i + \definedummyword\r + \definedummyword\sansserif + \definedummyword\sc + \definedummyword\slanted + \definedummyword\t + % + % Commands that take arguments. + \definedummyword\abbr + \definedummyword\acronym + \definedummyword\anchor + \definedummyword\cite + \definedummyword\code + \definedummyword\command + \definedummyword\dfn + \definedummyword\dmn + \definedummyword\email + \definedummyword\emph + \definedummyword\env + \definedummyword\file + \definedummyword\image + \definedummyword\indicateurl + \definedummyword\inforef + \definedummyword\kbd + \definedummyword\key + \definedummyword\math + \definedummyword\option + \definedummyword\pxref + \definedummyword\ref + \definedummyword\samp + \definedummyword\strong + \definedummyword\tie + \definedummyword\uref + \definedummyword\url + \definedummyword\var + \definedummyword\verb + \definedummyword\w + \definedummyword\xref +} + +% \indexnofonts is used when outputting the strings to sort the index +% by, and when constructing control sequence names. It eliminates all +% control sequences and just writes whatever the best ASCII sort string +% would be for a given command (usually its argument). +% +\def\indexnofonts{% + % Accent commands should become @asis. + \def\definedummyaccent##1{\let##1\asis}% + % We can just ignore other control letters. + \def\definedummyletter##1{\let##1\empty}% + % All control words become @asis by default; overrides below. + \let\definedummyword\definedummyaccent + % + \commondummiesnofonts + % + % Don't no-op \tt, since it isn't a user-level command + % and is used in the definitions of the active chars like <, >, |, etc. + % Likewise with the other plain tex font commands. + %\let\tt=\asis + % + \def\ { }% + \def\@{@}% + \def\_{\normalunderscore}% + \def\-{}% @- shouldn't affect sorting + % + % Unfortunately, texindex is not prepared to handle braces in the + % content at all. So for index sorting, we map @{ and @} to strings + % starting with |, since that ASCII character is between ASCII { and }. + \def\{{|a}% + \def\lbracechar{|a}% + % + \def\}{|b}% + \def\rbracechar{|b}% + % + % Non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\DH{DZZ}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\TH{ZZZ}% + \def\aa{aa}% + \def\ae{ae}% + \def\dh{dzz}% + \def\exclamdown{!}% + \def\l{l}% + \def\oe{oe}% + \def\ordf{a}% + \def\ordm{o}% + \def\o{o}% + \def\questiondown{?}% + \def\ss{ss}% + \def\th{zzz}% + % + \def\LaTeX{LaTeX}% + \def\TeX{TeX}% + % + % Assorted special characters. + % (The following {} will end up in the sort string, but that's ok.) + \def\arrow{->}% + \def\bullet{bullet}% + \def\comma{,}% + \def\copyright{copyright}% + \def\dots{...}% + \def\enddots{...}% + \def\equiv{==}% + \def\error{error}% + \def\euro{euro}% + \def\expansion{==>}% + \def\geq{>=}% + \def\guillemetleft{<<}% + \def\guillemetright{>>}% + \def\guilsinglleft{<}% + \def\guilsinglright{>}% + \def\leq{<=}% + \def\minus{-}% + \def\point{.}% + \def\pounds{pounds}% + \def\print{-|}% + \def\quotedblbase{"}% + \def\quotedblleft{"}% + \def\quotedblright{"}% + \def\quoteleft{`}% + \def\quoteright{'}% + \def\quotesinglbase{,}% + \def\registeredsymbol{R}% + \def\result{=>}% + \def\textdegree{o}% + % + \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax + \else \indexlquoteignore \fi + % + % We need to get rid of all macros, leaving only the arguments (if present). + % Of course this is not nearly correct, but it is the best we can do for now. + % makeinfo does not expand macros in the argument to @deffn, which ends up + % writing an index entry, and texindex isn't prepared for an index sort entry + % that starts with \. + % + % Since macro invocations are followed by braces, we can just redefine them + % to take a single TeX argument. The case of a macro invocation that + % goes to end-of-line is not handled. + % + \macrolist +} + +% Undocumented (for FSFS 2nd ed.): @set txiindexlquoteignore makes us +% ignore left quotes in the sort term. +{\catcode`\`=\active + \gdef\indexlquoteignore{\let`=\empty}} + +\let\indexbackslash=0 %overridden during \printindex. +\let\SETmarginindex=\relax % put index entries in margin (undocumented)? + +% Most index entries go through here, but \dosubind is the general case. +% #1 is the index name, #2 is the entry text. +\def\doind#1#2{\dosubind{#1}{#2}{}} + +% Workhorse for all \fooindexes. +% #1 is name of index, #2 is stuff to put there, #3 is subentry -- +% empty if called from \doind, as we usually are (the main exception +% is with most defuns, which call us directly). +% +\def\dosubind#1#2#3{% + \iflinks + {% + % Store the main index entry text (including the third arg). + \toks0 = {#2}% + % If third arg is present, precede it with a space. + \def\thirdarg{#3}% + \ifx\thirdarg\empty \else + \toks0 = \expandafter{\the\toks0 \space #3}% + \fi + % + \edef\writeto{\csname#1indfile\endcsname}% + % + \safewhatsit\dosubindwrite + }% + \fi +} + +% Write the entry in \toks0 to the index file: +% +\def\dosubindwrite{% + % Put the index entry in the margin if desired. + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% + \fi + % + % Remember, we are within a group. + \indexdummies % Must do this here, since \bf, etc expand at this stage + \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now + % so it will be output as is; and it will print as backslash. + % + % Process the index entry with all font commands turned off, to + % get the string to sort by. + {\indexnofonts + \edef\temp{\the\toks0}% need full expansion + \xdef\indexsorttmp{\temp}% + }% + % + % Set up the complete index entry, with both the sort key and + % the original text, including any font commands. We write + % three arguments to \entry to the .?? file (four in the + % subentry case), texindex reduces to two when writing the .??s + % sorted result. + \edef\temp{% + \write\writeto{% + \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% + }% + \temp +} + +% Take care of unwanted page breaks/skips around a whatsit: +% +% If a skip is the last thing on the list now, preserve it +% by backing up by \lastskip, doing the \write, then inserting +% the skip again. Otherwise, the whatsit generated by the +% \write or \pdfdest will make \lastskip zero. The result is that +% sequences like this: +% @end defun +% @tindex whatever +% @defun ... +% will have extra space inserted, because the \medbreak in the +% start of the @defun won't see the skip inserted by the @end of +% the previous defun. +% +% But don't do any of this if we're not in vertical mode. We +% don't want to do a \vskip and prematurely end a paragraph. +% +% Avoid page breaks due to these extra skips, too. +% +% But wait, there is a catch there: +% We'll have to check whether \lastskip is zero skip. \ifdim is not +% sufficient for this purpose, as it ignores stretch and shrink parts +% of the skip. The only way seems to be to check the textual +% representation of the skip. +% +% The following is almost like \def\zeroskipmacro{0.0pt} except that +% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). +% +\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} +% +\newskip\whatsitskip +\newcount\whatsitpenalty +% +% ..., ready, GO: +% +\def\safewhatsit#1{\ifhmode + #1% + \else + % \lastskip and \lastpenalty cannot both be nonzero simultaneously. + \whatsitskip = \lastskip + \edef\lastskipmacro{\the\lastskip}% + \whatsitpenalty = \lastpenalty + % + % If \lastskip is nonzero, that means the last item was a + % skip. And since a skip is discardable, that means this + % -\whatsitskip glue we're inserting is preceded by a + % non-discardable item, therefore it is not a potential + % breakpoint, therefore no \nobreak needed. + \ifx\lastskipmacro\zeroskipmacro + \else + \vskip-\whatsitskip + \fi + % + #1% + % + \ifx\lastskipmacro\zeroskipmacro + % If \lastskip was zero, perhaps the last item was a penalty, and + % perhaps it was >=10000, e.g., a \nobreak. In that case, we want + % to re-insert the same penalty (values >10000 are used for various + % signals); since we just inserted a non-discardable item, any + % following glue (such as a \parskip) would be a breakpoint. For example: + % @deffn deffn-whatever + % @vindex index-whatever + % Description. + % would allow a break between the index-whatever whatsit + % and the "Description." paragraph. + \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi + \else + % On the other hand, if we had a nonzero \lastskip, + % this make-up glue would be preceded by a non-discardable item + % (the whatsit from the \write), so we must insert a \nobreak. + \nobreak\vskip\whatsitskip + \fi +\fi} + +% The index entry written in the file actually looks like +% \entry {sortstring}{page}{topic} +% or +% \entry {sortstring}{page}{topic}{subtopic} +% The texindex program reads in these files and writes files +% containing these kinds of lines: +% \initial {c} +% before the first topic whose initial is c +% \entry {topic}{pagelist} +% for a topic that is used without subtopics +% \primary {topic} +% for the beginning of a topic that is used with subtopics +% \secondary {subtopic}{pagelist} +% for each subtopic. + +% Define the user-accessible indexing commands +% @findex, @vindex, @kindex, @cindex. + +\def\findex {\fnindex} +\def\kindex {\kyindex} +\def\cindex {\cpindex} +\def\vindex {\vrindex} +\def\tindex {\tpindex} +\def\pindex {\pgindex} + +\def\cindexsub {\begingroup\obeylines\cindexsub} +{\obeylines % +\gdef\cindexsub "#1" #2^^M{\endgroup % +\dosubind{cp}{#2}{#1}}} + +% Define the macros used in formatting output of the sorted index material. + +% @printindex causes a particular index (the ??s file) to get printed. +% It does not print any chapter heading (usually an @unnumbered). +% +\parseargdef\printindex{\begingroup + \dobreak \chapheadingskip{10000}% + % + \smallfonts \rm + \tolerance = 9500 + \plainfrenchspacing + \everypar = {}% don't want the \kern\-parindent from indentation suppression. + % + % See if the index file exists and is nonempty. + % Change catcode of @ here so that if the index file contains + % \initial {@} + % as its first line, TeX doesn't complain about mismatched braces + % (because it thinks @} is a control sequence). + \catcode`\@ = 11 + \openin 1 \jobname.#1s + \ifeof 1 + % \enddoublecolumns gets confused if there is no text in the index, + % and it loses the chapter title and the aux file entries for the + % index. The easiest way to prevent this problem is to make sure + % there is some text. + \putwordIndexNonexistent + \else + % + % If the index file exists but is empty, then \openin leaves \ifeof + % false. We have to make TeX try to read something from the file, so + % it can discover if there is anything in it. + \read 1 to \temp + \ifeof 1 + \putwordIndexIsEmpty + \else + % Index files are almost Texinfo source, but we use \ as the escape + % character. It would be better to use @, but that's too big a change + % to make right now. + \def\indexbackslash{\backslashcurfont}% + \catcode`\\ = 0 + \escapechar = `\\ + \begindoublecolumns + \input \jobname.#1s + \enddoublecolumns + \fi + \fi + \closein 1 +\endgroup} + +% These macros are used by the sorted index file itself. +% Change them to control the appearance of the index. + +\def\initial#1{{% + % Some minor font changes for the special characters. + \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt + % + % Remove any glue we may have, we'll be inserting our own. + \removelastskip + % + % We like breaks before the index initials, so insert a bonus. + \nobreak + \vskip 0pt plus 3\baselineskip + \penalty 0 + \vskip 0pt plus -3\baselineskip + % + % Typeset the initial. Making this add up to a whole number of + % baselineskips increases the chance of the dots lining up from column + % to column. It still won't often be perfect, because of the stretch + % we need before each entry, but it's better. + % + % No shrink because it confuses \balancecolumns. + \vskip 1.67\baselineskip plus .5\baselineskip + \leftline{\secbf #1}% + % Do our best not to break after the initial. + \nobreak + \vskip .33\baselineskip plus .1\baselineskip +}} + +% \entry typesets a paragraph consisting of the text (#1), dot leaders, and +% then page number (#2) flushed to the right margin. It is used for index +% and table of contents entries. The paragraph is indented by \leftskip. +% +% A straightforward implementation would start like this: +% \def\entry#1#2{... +% But this freezes the catcodes in the argument, and can cause problems to +% @code, which sets - active. This problem was fixed by a kludge--- +% ``-'' was active throughout whole index, but this isn't really right. +% The right solution is to prevent \entry from swallowing the whole text. +% --kasal, 21nov03 +\def\entry{% + \begingroup + % + % Start a new paragraph if necessary, so our assignments below can't + % affect previous text. + \par + % + % Do not fill out the last line with white space. + \parfillskip = 0in + % + % No extra space above this paragraph. + \parskip = 0in + % + % Do not prefer a separate line ending with a hyphen to fewer lines. + \finalhyphendemerits = 0 + % + % \hangindent is only relevant when the entry text and page number + % don't both fit on one line. In that case, bob suggests starting the + % dots pretty far over on the line. Unfortunately, a large + % indentation looks wrong when the entry text itself is broken across + % lines. So we use a small indentation and put up with long leaders. + % + % \hangafter is reset to 1 (which is the value we want) at the start + % of each paragraph, so we need not do anything with that. + \hangindent = 2em + % + % When the entry text needs to be broken, just fill out the first line + % with blank space. + \rightskip = 0pt plus1fil + % + % A bit of stretch before each entry for the benefit of balancing + % columns. + \vskip 0pt plus1pt + % + % When reading the text of entry, convert explicit line breaks + % from @* into spaces. The user might give these in long section + % titles, for instance. + \def\*{\unskip\space\ignorespaces}% + \def\entrybreak{\hfil\break}% + % + % Swallow the left brace of the text (first parameter): + \afterassignment\doentry + \let\temp = +} +\def\entrybreak{\unskip\space\ignorespaces}% +\def\doentry{% + \bgroup % Instead of the swallowed brace. + \noindent + \aftergroup\finishentry + % And now comes the text of the entry. +} +\def\finishentry#1{% + % #1 is the page number. + % + % The following is kludged to not output a line of dots in the index if + % there are no page numbers. The next person who breaks this will be + % cursed by a Unix daemon. + \setbox\boxA = \hbox{#1}% + \ifdim\wd\boxA = 0pt + \ % + \else + % + % If we must, put the page number on a line of its own, and fill out + % this line with blank space. (The \hfil is overwhelmed with the + % fill leaders glue in \indexdotfill if the page number does fit.) + \hfil\penalty50 + \null\nobreak\indexdotfill % Have leaders before the page number. + % + % The `\ ' here is removed by the implicit \unskip that TeX does as + % part of (the primitive) \par. Without it, a spurious underfull + % \hbox ensues. + \ifpdf + \pdfgettoks#1.% + \ \the\toksA + \else + \ #1% + \fi + \fi + \par + \endgroup +} + +% Like plain.tex's \dotfill, except uses up at least 1 em. +\def\indexdotfill{\cleaders + \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} + +\def\primary #1{\line{#1\hfil}} + +\newskip\secondaryindent \secondaryindent=0.5cm +\def\secondary#1#2{{% + \parfillskip=0in + \parskip=0in + \hangindent=1in + \hangafter=1 + \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill + \ifpdf + \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. + \else + #2 + \fi + \par +}} + +% Define two-column mode, which we use to typeset indexes. +% Adapted from the TeXbook, page 416, which is to say, +% the manmac.tex format used to print the TeXbook itself. +\catcode`\@=11 + +\newbox\partialpage +\newdimen\doublecolumnhsize + +\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns + % Grab any single-column material above us. + \output = {% + % + % Here is a possibility not foreseen in manmac: if we accumulate a + % whole lot of material, we might end up calling this \output + % routine twice in a row (see the doublecol-lose test, which is + % essentially a couple of indexes with @setchapternewpage off). In + % that case we just ship out what is in \partialpage with the normal + % output routine. Generally, \partialpage will be empty when this + % runs and this will be a no-op. See the indexspread.tex test case. + \ifvoid\partialpage \else + \onepageout{\pagecontents\partialpage}% + \fi + % + \global\setbox\partialpage = \vbox{% + % Unvbox the main output page. + \unvbox\PAGE + \kern-\topskip \kern\baselineskip + }% + }% + \eject % run that output routine to set \partialpage + % + % Use the double-column output routine for subsequent pages. + \output = {\doublecolumnout}% + % + % Change the page size parameters. We could do this once outside this + % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 + % format, but then we repeat the same computation. Repeating a couple + % of assignments once per index is clearly meaningless for the + % execution time, so we may as well do it in one place. + % + % First we halve the line length, less a little for the gutter between + % the columns. We compute the gutter based on the line length, so it + % changes automatically with the paper format. The magic constant + % below is chosen so that the gutter has the same value (well, +-<1pt) + % as it did when we hard-coded it. + % + % We put the result in a separate register, \doublecolumhsize, so we + % can restore it in \pagesofar, after \hsize itself has (potentially) + % been clobbered. + % + \doublecolumnhsize = \hsize + \advance\doublecolumnhsize by -.04154\hsize + \divide\doublecolumnhsize by 2 + \hsize = \doublecolumnhsize + % + % Double the \vsize as well. (We don't need a separate register here, + % since nobody clobbers \vsize.) + \vsize = 2\vsize +} + +% The double-column output routine for all double-column pages except +% the last. +% +\def\doublecolumnout{% + \splittopskip=\topskip \splitmaxdepth=\maxdepth + % Get the available space for the double columns -- the normal + % (undoubled) page height minus any material left over from the + % previous page. + \dimen@ = \vsize + \divide\dimen@ by 2 + \advance\dimen@ by -\ht\partialpage + % + % box0 will be the left-hand column, box2 the right. + \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ + \onepageout\pagesofar + \unvbox255 + \penalty\outputpenalty +} +% +% Re-output the contents of the output page -- any previous material, +% followed by the two boxes we just split, in box0 and box2. +\def\pagesofar{% + \unvbox\partialpage + % + \hsize = \doublecolumnhsize + \wd0=\hsize \wd2=\hsize + \hbox to\pagewidth{\box0\hfil\box2}% +} +% +% All done with double columns. +\def\enddoublecolumns{% + % The following penalty ensures that the page builder is exercised + % _before_ we change the output routine. This is necessary in the + % following situation: + % + % The last section of the index consists only of a single entry. + % Before this section, \pagetotal is less than \pagegoal, so no + % break occurs before the last section starts. However, the last + % section, consisting of \initial and the single \entry, does not + % fit on the page and has to be broken off. Without the following + % penalty the page builder will not be exercised until \eject + % below, and by that time we'll already have changed the output + % routine to the \balancecolumns version, so the next-to-last + % double-column page will be processed with \balancecolumns, which + % is wrong: The two columns will go to the main vertical list, with + % the broken-off section in the recent contributions. As soon as + % the output routine finishes, TeX starts reconsidering the page + % break. The two columns and the broken-off section both fit on the + % page, because the two columns now take up only half of the page + % goal. When TeX sees \eject from below which follows the final + % section, it invokes the new output routine that we've set after + % \balancecolumns below; \onepageout will try to fit the two columns + % and the final section into the vbox of \pageheight (see + % \pagebody), causing an overfull box. + % + % Note that glue won't work here, because glue does not exercise the + % page builder, unlike penalties (see The TeXbook, pp. 280-281). + \penalty0 + % + \output = {% + % Split the last of the double-column material. Leave it on the + % current page, no automatic page break. + \balancecolumns + % + % If we end up splitting too much material for the current page, + % though, there will be another page break right after this \output + % invocation ends. Having called \balancecolumns once, we do not + % want to call it again. Therefore, reset \output to its normal + % definition right away. (We hope \balancecolumns will never be + % called on to balance too much material, but if it is, this makes + % the output somewhat more palatable.) + \global\output = {\onepageout{\pagecontents\PAGE}}% + }% + \eject + \endgroup % started in \begindoublecolumns + % + % \pagegoal was set to the doubled \vsize above, since we restarted + % the current page. We're now back to normal single-column + % typesetting, so reset \pagegoal to the normal \vsize (after the + % \endgroup where \vsize got restored). + \pagegoal = \vsize +} +% +% Called at the end of the double column material. +\def\balancecolumns{% + \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. + \dimen@ = \ht0 + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip + \divide\dimen@ by 2 % target to split to + %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% + \splittopskip = \topskip + % Loop until we get a decent breakpoint. + {% + \vbadness = 10000 + \loop + \global\setbox3 = \copy0 + \global\setbox1 = \vsplit3 to \dimen@ + \ifdim\ht3>\dimen@ + \global\advance\dimen@ by 1pt + \repeat + }% + %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + % + \pagesofar +} +\catcode`\@ = \other + + +\message{sectioning,} +% Chapters, sections, etc. + +% Let's start with @part. +\outer\parseargdef\part{\partzzz{#1}} +\def\partzzz#1{% + \chapoddpage + \null + \vskip.3\vsize % move it down on the page a bit + \begingroup + \noindent \titlefonts\rmisbold #1\par % the text + \let\lastnode=\empty % no node to associate with + \writetocentry{part}{#1}{}% but put it in the toc + \headingsoff % no headline or footline on the part page + \chapoddpage + \endgroup +} + +% \unnumberedno is an oxymoron. But we count the unnumbered +% sections so that we can refer to them unambiguously in the pdf +% outlines by their "section number". We avoid collisions with chapter +% numbers by starting them at 10000. (If a document ever has 10000 +% chapters, we're in trouble anyway, I'm sure.) +\newcount\unnumberedno \unnumberedno = 10000 +\newcount\chapno +\newcount\secno \secno=0 +\newcount\subsecno \subsecno=0 +\newcount\subsubsecno \subsubsecno=0 + +% This counter is funny since it counts through charcodes of letters A, B, ... +\newcount\appendixno \appendixno = `\@ +% +% \def\appendixletter{\char\the\appendixno} +% We do the following ugly conditional instead of the above simple +% construct for the sake of pdftex, which needs the actual +% letter in the expansion, not just typeset. +% +\def\appendixletter{% + \ifnum\appendixno=`A A% + \else\ifnum\appendixno=`B B% + \else\ifnum\appendixno=`C C% + \else\ifnum\appendixno=`D D% + \else\ifnum\appendixno=`E E% + \else\ifnum\appendixno=`F F% + \else\ifnum\appendixno=`G G% + \else\ifnum\appendixno=`H H% + \else\ifnum\appendixno=`I I% + \else\ifnum\appendixno=`J J% + \else\ifnum\appendixno=`K K% + \else\ifnum\appendixno=`L L% + \else\ifnum\appendixno=`M M% + \else\ifnum\appendixno=`N N% + \else\ifnum\appendixno=`O O% + \else\ifnum\appendixno=`P P% + \else\ifnum\appendixno=`Q Q% + \else\ifnum\appendixno=`R R% + \else\ifnum\appendixno=`S S% + \else\ifnum\appendixno=`T T% + \else\ifnum\appendixno=`U U% + \else\ifnum\appendixno=`V V% + \else\ifnum\appendixno=`W W% + \else\ifnum\appendixno=`X X% + \else\ifnum\appendixno=`Y Y% + \else\ifnum\appendixno=`Z Z% + % The \the is necessary, despite appearances, because \appendixletter is + % expanded while writing the .toc file. \char\appendixno is not + % expandable, thus it is written literally, thus all appendixes come out + % with the same letter (or @) in the toc without it. + \else\char\the\appendixno + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi + \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} + +% Each @chapter defines these (using marks) as the number+name, number +% and name of the chapter. Page headings and footings can use +% these. @section does likewise. +\def\thischapter{} +\def\thischapternum{} +\def\thischaptername{} +\def\thissection{} +\def\thissectionnum{} +\def\thissectionname{} + +\newcount\absseclevel % used to calculate proper heading level +\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count + +% @raisesections: treat @section as chapter, @subsection as section, etc. +\def\raisesections{\global\advance\secbase by -1} +\let\up=\raisesections % original BFox name + +% @lowersections: treat @chapter as section, @section as subsection, etc. +\def\lowersections{\global\advance\secbase by 1} +\let\down=\lowersections % original BFox name + +% we only have subsub. +\chardef\maxseclevel = 3 +% +% A numbered section within an unnumbered changes to unnumbered too. +% To achieve this, remember the "biggest" unnum. sec. we are currently in: +\chardef\unnlevel = \maxseclevel +% +% Trace whether the current chapter is an appendix or not: +% \chapheadtype is "N" or "A", unnumbered chapters are ignored. +\def\chapheadtype{N} + +% Choose a heading macro +% #1 is heading type +% #2 is heading level +% #3 is text for heading +\def\genhead#1#2#3{% + % Compute the abs. sec. level: + \absseclevel=#2 + \advance\absseclevel by \secbase + % Make sure \absseclevel doesn't fall outside the range: + \ifnum \absseclevel < 0 + \absseclevel = 0 + \else + \ifnum \absseclevel > 3 + \absseclevel = 3 + \fi + \fi + % The heading type: + \def\headtype{#1}% + \if \headtype U% + \ifnum \absseclevel < \unnlevel + \chardef\unnlevel = \absseclevel + \fi + \else + % Check for appendix sections: + \ifnum \absseclevel = 0 + \edef\chapheadtype{\headtype}% + \else + \if \headtype A\if \chapheadtype N% + \errmessage{@appendix... within a non-appendix chapter}% + \fi\fi + \fi + % Check for numbered within unnumbered: + \ifnum \absseclevel > \unnlevel + \def\headtype{U}% + \else + \chardef\unnlevel = 3 + \fi + \fi + % Now print the heading: + \if \headtype U% + \ifcase\absseclevel + \unnumberedzzz{#3}% + \or \unnumberedseczzz{#3}% + \or \unnumberedsubseczzz{#3}% + \or \unnumberedsubsubseczzz{#3}% + \fi + \else + \if \headtype A% + \ifcase\absseclevel + \appendixzzz{#3}% + \or \appendixsectionzzz{#3}% + \or \appendixsubseczzz{#3}% + \or \appendixsubsubseczzz{#3}% + \fi + \else + \ifcase\absseclevel + \chapterzzz{#3}% + \or \seczzz{#3}% + \or \numberedsubseczzz{#3}% + \or \numberedsubsubseczzz{#3}% + \fi + \fi + \fi + \suppressfirstparagraphindent +} + +% an interface: +\def\numhead{\genhead N} +\def\apphead{\genhead A} +\def\unnmhead{\genhead U} + +% @chapter, @appendix, @unnumbered. Increment top-level counter, reset +% all lower-level sectioning counters to zero. +% +% Also set \chaplevelprefix, which we prepend to @float sequence numbers +% (e.g., figures), q.v. By default (before any chapter), that is empty. +\let\chaplevelprefix = \empty +% +\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz +\def\chapterzzz#1{% + % section resetting is \global in case the chapter is in a group, such + % as an @include file. + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\chapno by 1 + % + % Used for \float. + \gdef\chaplevelprefix{\the\chapno.}% + \resetallfloatnos + % + % \putwordChapter can contain complex things in translations. + \toks0=\expandafter{\putwordChapter}% + \message{\the\toks0 \space \the\chapno}% + % + % Write the actual heading. + \chapmacro{#1}{Ynumbered}{\the\chapno}% + % + % So @section and the like are numbered underneath this chapter. + \global\let\section = \numberedsec + \global\let\subsection = \numberedsubsec + \global\let\subsubsection = \numberedsubsubsec +} + +\outer\parseargdef\appendix{\apphead0{#1}} % normally calls appendixzzz +% +\def\appendixzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\appendixno by 1 + \gdef\chaplevelprefix{\appendixletter.}% + \resetallfloatnos + % + % \putwordAppendix can contain complex things in translations. + \toks0=\expandafter{\putwordAppendix}% + \message{\the\toks0 \space \appendixletter}% + % + \chapmacro{#1}{Yappendix}{\appendixletter}% + % + \global\let\section = \appendixsec + \global\let\subsection = \appendixsubsec + \global\let\subsubsection = \appendixsubsubsec +} + +% normally unnmhead0 calls unnumberedzzz: +\outer\parseargdef\unnumbered{\unnmhead0{#1}} +\def\unnumberedzzz#1{% + \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 + \global\advance\unnumberedno by 1 + % + % Since an unnumbered has no number, no prefix for figures. + \global\let\chaplevelprefix = \empty + \resetallfloatnos + % + % This used to be simply \message{#1}, but TeX fully expands the + % argument to \message. Therefore, if #1 contained @-commands, TeX + % expanded them. For example, in `@unnumbered The @cite{Book}', TeX + % expanded @cite (which turns out to cause errors because \cite is meant + % to be executed, not expanded). + % + % Anyway, we don't want the fully-expanded definition of @cite to appear + % as a result of the \message, we just want `@cite' itself. We use + % \the to achieve this: TeX expands \the only once, + % simply yielding the contents of . (We also do this for + % the toc entries.) + \toks0 = {#1}% + \message{(\the\toks0)}% + % + \chapmacro{#1}{Ynothing}{\the\unnumberedno}% + % + \global\let\section = \unnumberedsec + \global\let\subsection = \unnumberedsubsec + \global\let\subsubsection = \unnumberedsubsubsec +} + +% @centerchap is like @unnumbered, but the heading is centered. +\outer\parseargdef\centerchap{% + % Well, we could do the following in a group, but that would break + % an assumption that \chapmacro is called at the outermost level. + % Thus we are safer this way: --kasal, 24feb04 + \let\centerparametersmaybe = \centerparameters + \unnmhead0{#1}% + \let\centerparametersmaybe = \relax +} + +% @top is like @unnumbered. +\let\top\unnumbered + +% Sections. +% +\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz +\def\seczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% +} + +% normally calls appendixsectionzzz: +\outer\parseargdef\appendixsection{\apphead1{#1}} +\def\appendixsectionzzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% +} +\let\appendixsec\appendixsection + +% normally calls unnumberedseczzz: +\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} +\def\unnumberedseczzz#1{% + \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 + \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% +} + +% Subsections. +% +% normally calls numberedsubseczzz: +\outer\parseargdef\numberedsubsec{\numhead2{#1}} +\def\numberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% +} + +% normally calls appendixsubseczzz: +\outer\parseargdef\appendixsubsec{\apphead2{#1}} +\def\appendixsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno}% +} + +% normally calls unnumberedsubseczzz: +\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} +\def\unnumberedsubseczzz#1{% + \global\subsubsecno=0 \global\advance\subsecno by 1 + \sectionheading{#1}{subsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno}% +} + +% Subsubsections. +% +% normally numberedsubsubseczzz: +\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} +\def\numberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynumbered}% + {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +% normally appendixsubsubseczzz: +\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} +\def\appendixsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Yappendix}% + {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +% normally unnumberedsubsubseczzz: +\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} +\def\unnumberedsubsubseczzz#1{% + \global\advance\subsubsecno by 1 + \sectionheading{#1}{subsubsec}{Ynothing}% + {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% +} + +% These macros control what the section commands do, according +% to what kind of chapter we are in (ordinary, appendix, or unnumbered). +% Define them by default for a numbered chapter. +\let\section = \numberedsec +\let\subsection = \numberedsubsec +\let\subsubsection = \numberedsubsubsec + +% Define @majorheading, @heading and @subheading + +\def\majorheading{% + {\advance\chapheadingskip by 10pt \chapbreak }% + \parsearg\chapheadingzzz +} + +\def\chapheading{\chapbreak \parsearg\chapheadingzzz} +\def\chapheadingzzz#1{% + \vbox{\chapfonts \raggedtitlesettings #1\par}% + \nobreak\bigskip \nobreak + \suppressfirstparagraphindent +} + +% @heading, @subheading, @subsubheading. +\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} +\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} + \suppressfirstparagraphindent} + +% These macros generate a chapter, section, etc. heading only +% (including whitespace, linebreaking, etc. around it), +% given all the information in convenient, parsed form. + +% Args are the skip and penalty (usually negative) +\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} + +% Parameter controlling skip before chapter headings (if needed) +\newskip\chapheadingskip + +% Define plain chapter starts, and page on/off switching for it. +\def\chapbreak{\dobreak \chapheadingskip {-4000}} +\def\chappager{\par\vfill\supereject} +% Because \domark is called before \chapoddpage, the filler page will +% get the headings for the next chapter, which is wrong. But we don't +% care -- we just disable all headings on the filler page. +\def\chapoddpage{% + \chappager + \ifodd\pageno \else + \begingroup + \headingsoff + \null + \chappager + \endgroup + \fi +} + +\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} + +\def\CHAPPAGoff{% +\global\let\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chapbreak +\global\let\pagealignmacro=\chappager} + +\def\CHAPPAGon{% +\global\let\contentsalignmacro = \chappager +\global\let\pchapsepmacro=\chappager +\global\let\pagealignmacro=\chappager +\global\def\HEADINGSon{\HEADINGSsingle}} + +\def\CHAPPAGodd{% +\global\let\contentsalignmacro = \chapoddpage +\global\let\pchapsepmacro=\chapoddpage +\global\let\pagealignmacro=\chapoddpage +\global\def\HEADINGSon{\HEADINGSdouble}} + +\CHAPPAGon + +% Chapter opening. +% +% #1 is the text, #2 is the section type (Ynumbered, Ynothing, +% Yappendix, Yomitfromtoc), #3 the chapter number. +% +% To test against our argument. +\def\Ynothingkeyword{Ynothing} +\def\Yomitfromtockeyword{Yomitfromtoc} +\def\Yappendixkeyword{Yappendix} +% +\def\chapmacro#1#2#3{% + % Insert the first mark before the heading break (see notes for \domark). + \let\prevchapterdefs=\lastchapterdefs + \let\prevsectiondefs=\lastsectiondefs + \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}% + \gdef\thissection{}}% + % + \def\temptype{#2}% + \ifx\temptype\Ynothingkeyword + \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\thischapter{\thischaptername}}% + \else\ifx\temptype\Yomitfromtockeyword + \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\thischapter{}}% + \else\ifx\temptype\Yappendixkeyword + \toks0={#1}% + \xdef\lastchapterdefs{% + \gdef\noexpand\thischaptername{\the\toks0}% + \gdef\noexpand\thischapternum{\appendixletter}% + % \noexpand\putwordAppendix avoids expanding indigestible + % commands in some of the translations. + \gdef\noexpand\thischapter{\noexpand\putwordAppendix{} + \noexpand\thischapternum: + \noexpand\thischaptername}% + }% + \else + \toks0={#1}% + \xdef\lastchapterdefs{% + \gdef\noexpand\thischaptername{\the\toks0}% + \gdef\noexpand\thischapternum{\the\chapno}% + % \noexpand\putwordChapter avoids expanding indigestible + % commands in some of the translations. + \gdef\noexpand\thischapter{\noexpand\putwordChapter{} + \noexpand\thischapternum: + \noexpand\thischaptername}% + }% + \fi\fi\fi + % + % Output the mark. Pass it through \safewhatsit, to take care of + % the preceding space. + \safewhatsit\domark + % + % Insert the chapter heading break. + \pchapsepmacro + % + % Now the second mark, after the heading break. No break points + % between here and the heading. + \let\prevchapterdefs=\lastchapterdefs + \let\prevsectiondefs=\lastsectiondefs + \domark + % + {% + \chapfonts \rmisbold + % + % Have to define \lastsection before calling \donoderef, because the + % xref code eventually uses it. On the other hand, it has to be called + % after \pchapsepmacro, or the headline will change too soon. + \gdef\lastsection{#1}% + % + % Only insert the separating space if we have a chapter/appendix + % number, and don't print the unnumbered ``number''. + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unnchap}% + \else\ifx\temptype\Yomitfromtockeyword + \setbox0 = \hbox{}% contents like unnumbered, but no toc entry + \def\toctype{omit}% + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% + \def\toctype{app}% + \else + \setbox0 = \hbox{#3\enspace}% + \def\toctype{numchap}% + \fi\fi\fi + % + % Write the toc entry for this chapter. Must come before the + % \donoderef, because we include the current node name in the toc + % entry, and \donoderef resets it to empty. + \writetocentry{\toctype}{#1}{#3}% + % + % For pdftex, we have to write out the node definition (aka, make + % the pdfdest) after any page break, but before the actual text has + % been typeset. If the destination for the pdf outline is after the + % text, then jumping from the outline may wind up with the text not + % being visible, for instance under high magnification. + \donoderef{#2}% + % + % Typeset the actual heading. + \nobreak % Avoid page breaks at the interline glue. + \vbox{\raggedtitlesettings \hangindent=\wd0 \centerparametersmaybe + \unhbox0 #1\par}% + }% + \nobreak\bigskip % no page break after a chapter title + \nobreak +} + +% @centerchap -- centered and unnumbered. +\let\centerparametersmaybe = \relax +\def\centerparameters{% + \advance\rightskip by 3\rightskip + \leftskip = \rightskip + \parfillskip = 0pt +} + + +% I don't think this chapter style is supported any more, so I'm not +% updating it with the new noderef stuff. We'll see. --karl, 11aug03. +% +\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} +% +\def\unnchfopen #1{% + \chapoddpage + \vbox{\chapfonts \raggedtitlesettings #1\par}% + \nobreak\bigskip\nobreak +} +\def\chfopen #1#2{\chapoddpage {\chapfonts +\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% +\par\penalty 5000 % +} +\def\centerchfopen #1{% + \chapoddpage + \vbox{\chapfonts \raggedtitlesettings \hfill #1\hfill}% + \nobreak\bigskip \nobreak +} +\def\CHAPFopen{% + \global\let\chapmacro=\chfopen + \global\let\centerchapmacro=\centerchfopen} + + +% Section titles. These macros combine the section number parts and +% call the generic \sectionheading to do the printing. +% +\newskip\secheadingskip +\def\secheadingbreak{\dobreak \secheadingskip{-1000}} + +% Subsection titles. +\newskip\subsecheadingskip +\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} + +% Subsubsection titles. +\def\subsubsecheadingskip{\subsecheadingskip} +\def\subsubsecheadingbreak{\subsecheadingbreak} + + +% Print any size, any type, section title. +% +% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is +% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the +% section number. +% +\def\seckeyword{sec} +% +\def\sectionheading#1#2#3#4{% + {% + \checkenv{}% should not be in an environment. + % + % Switch to the right set of fonts. + \csname #2fonts\endcsname \rmisbold + % + \def\sectionlevel{#2}% + \def\temptype{#3}% + % + % Insert first mark before the heading break (see notes for \domark). + \let\prevsectiondefs=\lastsectiondefs + \ifx\temptype\Ynothingkeyword + \ifx\sectionlevel\seckeyword + \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}% + \gdef\thissection{\thissectionname}}% + \fi + \else\ifx\temptype\Yomitfromtockeyword + % Don't redefine \thissection. + \else\ifx\temptype\Yappendixkeyword + \ifx\sectionlevel\seckeyword + \toks0={#1}% + \xdef\lastsectiondefs{% + \gdef\noexpand\thissectionname{\the\toks0}% + \gdef\noexpand\thissectionnum{#4}% + % \noexpand\putwordSection avoids expanding indigestible + % commands in some of the translations. + \gdef\noexpand\thissection{\noexpand\putwordSection{} + \noexpand\thissectionnum: + \noexpand\thissectionname}% + }% + \fi + \else + \ifx\sectionlevel\seckeyword + \toks0={#1}% + \xdef\lastsectiondefs{% + \gdef\noexpand\thissectionname{\the\toks0}% + \gdef\noexpand\thissectionnum{#4}% + % \noexpand\putwordSection avoids expanding indigestible + % commands in some of the translations. + \gdef\noexpand\thissection{\noexpand\putwordSection{} + \noexpand\thissectionnum: + \noexpand\thissectionname}% + }% + \fi + \fi\fi\fi + % + % Go into vertical mode. Usually we'll already be there, but we + % don't want the following whatsit to end up in a preceding paragraph + % if the document didn't happen to have a blank line. + \par + % + % Output the mark. Pass it through \safewhatsit, to take care of + % the preceding space. + \safewhatsit\domark + % + % Insert space above the heading. + \csname #2headingbreak\endcsname + % + % Now the second mark, after the heading break. No break points + % between here and the heading. + \let\prevsectiondefs=\lastsectiondefs + \domark + % + % Only insert the space after the number if we have a section number. + \ifx\temptype\Ynothingkeyword + \setbox0 = \hbox{}% + \def\toctype{unn}% + \gdef\lastsection{#1}% + \else\ifx\temptype\Yomitfromtockeyword + % for @headings -- no section number, don't include in toc, + % and don't redefine \lastsection. + \setbox0 = \hbox{}% + \def\toctype{omit}% + \let\sectionlevel=\empty + \else\ifx\temptype\Yappendixkeyword + \setbox0 = \hbox{#4\enspace}% + \def\toctype{app}% + \gdef\lastsection{#1}% + \else + \setbox0 = \hbox{#4\enspace}% + \def\toctype{num}% + \gdef\lastsection{#1}% + \fi\fi\fi + % + % Write the toc entry (before \donoderef). See comments in \chapmacro. + \writetocentry{\toctype\sectionlevel}{#1}{#4}% + % + % Write the node reference (= pdf destination for pdftex). + % Again, see comments in \chapmacro. + \donoderef{#3}% + % + % Interline glue will be inserted when the vbox is completed. + % That glue will be a valid breakpoint for the page, since it'll be + % preceded by a whatsit (usually from the \donoderef, or from the + % \writetocentry if there was no node). We don't want to allow that + % break, since then the whatsits could end up on page n while the + % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. + \nobreak + % + % Output the actual section heading. + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright + \hangindent=\wd0 % zero if no section number + \unhbox0 #1}% + }% + % Add extra space after the heading -- half of whatever came above it. + % Don't allow stretch, though. + \kern .5 \csname #2headingskip\endcsname + % + % Do not let the kern be a potential breakpoint, as it would be if it + % was followed by glue. + \nobreak + % + % We'll almost certainly start a paragraph next, so don't let that + % glue accumulate. (Not a breakpoint because it's preceded by a + % discardable item.) However, when a paragraph is not started next + % (\startdefun, \cartouche, \center, etc.), this needs to be wiped out + % or the negative glue will cause weirdly wrong output, typically + % obscuring the section heading with something else. + \vskip-\parskip + % + % This is so the last item on the main vertical list is a known + % \penalty > 10000, so \startdefun, etc., can recognize the situation + % and do the needful. + \penalty 10001 +} + + +\message{toc,} +% Table of contents. +\newwrite\tocfile + +% Write an entry to the toc file, opening it if necessary. +% Called from @chapter, etc. +% +% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} +% We append the current node name (if any) and page number as additional +% arguments for the \{chap,sec,...}entry macros which will eventually +% read this. The node name is used in the pdf outlines as the +% destination to jump to. +% +% We open the .toc file for writing here instead of at @setfilename (or +% any other fixed time) so that @contents can be anywhere in the document. +% But if #1 is `omit', then we don't do anything. This is used for the +% table of contents chapter openings themselves. +% +\newif\iftocfileopened +\def\omitkeyword{omit}% +% +\def\writetocentry#1#2#3{% + \edef\writetoctype{#1}% + \ifx\writetoctype\omitkeyword \else + \iftocfileopened\else + \immediate\openout\tocfile = \jobname.toc + \global\tocfileopenedtrue + \fi + % + \iflinks + {\atdummies + \edef\temp{% + \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% + \temp + }% + \fi + \fi + % + % Tell \shipout to create a pdf destination on each page, if we're + % writing pdf. These are used in the table of contents. We can't + % just write one on every page because the title pages are numbered + % 1 and 2 (the page numbers aren't printed), and so are the first + % two pages of the document. Thus, we'd have two destinations named + % `1', and two named `2'. + \ifpdf \global\pdfmakepagedesttrue \fi +} + + +% These characters do not print properly in the Computer Modern roman +% fonts, so we must take special care. This is more or less redundant +% with the Texinfo input format setup at the end of this file. +% +\def\activecatcodes{% + \catcode`\"=\active + \catcode`\$=\active + \catcode`\<=\active + \catcode`\>=\active + \catcode`\\=\active + \catcode`\^=\active + \catcode`\_=\active + \catcode`\|=\active + \catcode`\~=\active +} + + +% Read the toc file, which is essentially Texinfo input. +\def\readtocfile{% + \setupdatafile + \activecatcodes + \input \tocreadfilename +} + +\newskip\contentsrightmargin \contentsrightmargin=1in +\newcount\savepageno +\newcount\lastnegativepageno \lastnegativepageno = -1 + +% Prepare to read what we've written to \tocfile. +% +\def\startcontents#1{% + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund + \contentsalignmacro + \immediate\closeout\tocfile + % + % Don't need to put `Contents' or `Short Contents' in the headline. + % It is abundantly clear what they are. + \chapmacro{#1}{Yomitfromtoc}{}% + % + \savepageno = \pageno + \begingroup % Set up to handle contents files properly. + \raggedbottom % Worry more about breakpoints than the bottom. + \advance\hsize by -\contentsrightmargin % Don't use the full line length. + % + % Roman numerals for page numbers. + \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi +} + +% redefined for the two-volume lispref. We always output on +% \jobname.toc even if this is redefined. +% +\def\tocreadfilename{\jobname.toc} + +% Normal (long) toc. +% +\def\contents{% + \startcontents{\putwordTOC}% + \openin 1 \tocreadfilename\space + \ifeof 1 \else + \readtocfile + \fi + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \ifeof 1 \else + \pdfmakeoutlines + \fi + \closein 1 + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} + +% And just the chapters. +\def\summarycontents{% + \startcontents{\putwordShortTOC}% + % + \let\partentry = \shortpartentry + \let\numchapentry = \shortchapentry + \let\appentry = \shortchapentry + \let\unnchapentry = \shortunnchapentry + % We want a true roman here for the page numbers. + \secfonts + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt + \rm + \hyphenpenalty = 10000 + \advance\baselineskip by 1pt % Open it up a little. + \def\numsecentry##1##2##3##4{} + \let\appsecentry = \numsecentry + \let\unnsecentry = \numsecentry + \let\numsubsecentry = \numsecentry + \let\appsubsecentry = \numsecentry + \let\unnsubsecentry = \numsecentry + \let\numsubsubsecentry = \numsecentry + \let\appsubsubsecentry = \numsecentry + \let\unnsubsubsecentry = \numsecentry + \openin 1 \tocreadfilename\space + \ifeof 1 \else + \readtocfile + \fi + \closein 1 + \vfill \eject + \contentsalignmacro % in case @setchapternewpage odd is in effect + \endgroup + \lastnegativepageno = \pageno + \global\pageno = \savepageno +} +\let\shortcontents = \summarycontents + +% Typeset the label for a chapter or appendix for the short contents. +% The arg is, e.g., `A' for an appendix, or `3' for a chapter. +% +\def\shortchaplabel#1{% + % This space should be enough, since a single number is .5em, and the + % widest letter (M) is 1em, at least in the Computer Modern fonts. + % But use \hss just in case. + % (This space doesn't include the extra space that gets added after + % the label; that gets put in by \shortchapentry above.) + % + % We'd like to right-justify chapter numbers, but that looks strange + % with appendix letters. And right-justifying numbers and + % left-justifying letters looks strange when there is less than 10 + % chapters. Have to read the whole toc once to know how many chapters + % there are before deciding ... + \hbox to 1em{#1\hss}% +} + +% These macros generate individual entries in the table of contents. +% The first argument is the chapter or section name. +% The last argument is the page number. +% The arguments in between are the chapter number, section number, ... + +% Parts, in the main contents. Replace the part number, which doesn't +% exist, with an empty box. Let's hope all the numbers have the same width. +% Also ignore the page number, which is conventionally not printed. +\def\numeralbox{\setbox0=\hbox{8}\hbox to \wd0{\hfil}} +\def\partentry#1#2#3#4{\dochapentry{\numeralbox\labelspace#1}{}} +% +% Parts, in the short toc. +\def\shortpartentry#1#2#3#4{% + \penalty-300 + \vskip.5\baselineskip plus.15\baselineskip minus.1\baselineskip + \shortchapentry{{\bf #1}}{\numeralbox}{}{}% +} + +% Chapters, in the main contents. +\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} +% +% Chapters, in the short toc. +% See comments in \dochapentry re vbox and related settings. +\def\shortchapentry#1#2#3#4{% + \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% +} + +% Appendices, in the main contents. +% Need the word Appendix, and a fixed-size box. +% +\def\appendixbox#1{% + % We use M since it's probably the widest letter. + \setbox0 = \hbox{\putwordAppendix{} M}% + \hbox to \wd0{\putwordAppendix{} #1\hss}} +% +\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} + +% Unnumbered chapters. +\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} +\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} + +% Sections. +\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} +\let\appsecentry=\numsecentry +\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} + +% Subsections. +\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} +\let\appsubsecentry=\numsubsecentry +\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} + +% And subsubsections. +\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} +\let\appsubsubsecentry=\numsubsubsecentry +\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} + +% This parameter controls the indentation of the various levels. +% Same as \defaultparindent. +\newdimen\tocindent \tocindent = 15pt + +% Now for the actual typesetting. In all these, #1 is the text and #2 is the +% page number. +% +% If the toc has to be broken over pages, we want it to be at chapters +% if at all possible; hence the \penalty. +\def\dochapentry#1#2{% + \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip + \begingroup + \chapentryfonts + \tocentry{#1}{\dopageno\bgroup#2\egroup}% + \endgroup + \nobreak\vskip .25\baselineskip plus.1\baselineskip +} + +\def\dosecentry#1#2{\begingroup + \secentryfonts \leftskip=\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsecentry#1#2{\begingroup + \subsecentryfonts \leftskip=2\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +\def\dosubsubsecentry#1#2{\begingroup + \subsubsecentryfonts \leftskip=3\tocindent + \tocentry{#1}{\dopageno\bgroup#2\egroup}% +\endgroup} + +% We use the same \entry macro as for the index entries. +\let\tocentry = \entry + +% Space between chapter (or whatever) number and the title. +\def\labelspace{\hskip1em \relax} + +\def\dopageno#1{{\rm #1}} +\def\doshortpageno#1{{\rm #1}} + +\def\chapentryfonts{\secfonts \rm} +\def\secentryfonts{\textfonts} +\def\subsecentryfonts{\textfonts} +\def\subsubsecentryfonts{\textfonts} + + +\message{environments,} +% @foo ... @end foo. + +% @tex ... @end tex escapes into raw TeX temporarily. +% One exception: @ is still an escape character, so that @end tex works. +% But \@ or @@ will get a plain @ character. + +\envdef\tex{% + \setupmarkupstyle{tex}% + \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 + \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 + \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie + \catcode `\%=14 + \catcode `\+=\other + \catcode `\"=\other + \catcode `\|=\other + \catcode `\<=\other + \catcode `\>=\other + \catcode`\`=\other + \catcode`\'=\other + \escapechar=`\\ + % + % ' is active in math mode (mathcode"8000). So reset it, and all our + % other math active characters (just in case), to plain's definitions. + \mathactive + % + \let\b=\ptexb + \let\bullet=\ptexbullet + \let\c=\ptexc + \let\,=\ptexcomma + \let\.=\ptexdot + \let\dots=\ptexdots + \let\equiv=\ptexequiv + \let\!=\ptexexclam + \let\i=\ptexi + \let\indent=\ptexindent + \let\noindent=\ptexnoindent + \let\{=\ptexlbrace + \let\+=\tabalign + \let\}=\ptexrbrace + \let\/=\ptexslash + \let\*=\ptexstar + \let\t=\ptext + \expandafter \let\csname top\endcsname=\ptextop % outer + \let\frenchspacing=\plainfrenchspacing + % + \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% + \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% + \def\@{@}% +} +% There is no need to define \Etex. + +% Define @lisp ... @end lisp. +% @lisp environment forms a group so it can rebind things, +% including the definition of @end lisp (which normally is erroneous). + +% Amount to narrow the margins by for @lisp. +\newskip\lispnarrowing \lispnarrowing=0.4in + +% This is the definition that ^^M gets inside @lisp, @example, and other +% such environments. \null is better than a space, since it doesn't +% have any width. +\def\lisppar{\null\endgraf} + +% This space is always present above and below environments. +\newskip\envskipamount \envskipamount = 0pt + +% Make spacing and below environment symmetrical. We use \parskip here +% to help in doing that, since in @example-like environments \parskip +% is reset to zero; thus the \afterenvbreak inserts no space -- but the +% start of the next paragraph will insert \parskip. +% +\def\aboveenvbreak{{% + % =10000 instead of <10000 because of a special case in \itemzzz and + % \sectionheading, q.v. + \ifnum \lastpenalty=10000 \else + \advance\envskipamount by \parskip + \endgraf + \ifdim\lastskip<\envskipamount + \removelastskip + % it's not a good place to break if the last penalty was \nobreak + % or better ... + \ifnum\lastpenalty<10000 \penalty-50 \fi + \vskip\envskipamount + \fi + \fi +}} + +\let\afterenvbreak = \aboveenvbreak + +% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will +% also clear it, so that its embedded environments do the narrowing again. +\let\nonarrowing=\relax + +% @cartouche ... @end cartouche: draw rectangle w/rounded corners around +% environment contents. +\font\circle=lcircle10 +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip +\circthick=\fontdimen8\circle +% +\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth +\def\ctr{{\hskip 6pt\circle\char'010}} +\def\cbl{{\circle\char'012\hskip -6pt}} +\def\cbr{{\hskip 6pt\circle\char'011}} +\def\carttop{\hbox to \cartouter{\hskip\lskip + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} +\def\cartbot{\hbox to \cartouter{\hskip\lskip + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} +% +\newskip\lskip\newskip\rskip + +\envdef\cartouche{% + \ifhmode\par\fi % can't be in the midst of a paragraph. + \startsavinginserts + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt % we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18.4pt % allow for 3pt kerns on either + % side, and for 6pt waste from + % each corner char, and rule thickness + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing = t% + % + % If this cartouche directly follows a sectioning command, we need the + % \parskip glue (backspaced over by default) or the cartouche can + % collide with the section heading. + \ifnum\lastpenalty>10000 \vskip\parskip \penalty\lastpenalty \fi + % + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \kern3pt + \hsize=\cartinner + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip + \comment % For explanation, see the end of def\group. +} +\def\Ecartouche{% + \ifhmode\par\fi + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup + \checkinserts +} + + +% This macro is called at the beginning of all the @example variants, +% inside a group. +\newdimen\nonfillparindent +\def\nonfillstart{% + \aboveenvbreak + \hfuzz = 12pt % Don't be fussy + \sepspaces % Make spaces be word-separators rather than space tokens. + \let\par = \lisppar % don't ignore blank lines + \obeylines % each line of input is a line of output + \parskip = 0pt + % Turn off paragraph indentation but redefine \indent to emulate + % the normal \indent. + \nonfillparindent=\parindent + \parindent = 0pt + \let\indent\nonfillindent + % + \emergencystretch = 0pt % don't try to avoid overfull boxes + \ifx\nonarrowing\relax + \advance \leftskip by \lispnarrowing + \exdentamount=\lispnarrowing + \else + \let\nonarrowing = \relax + \fi + \let\exdent=\nofillexdent +} + +\begingroup +\obeyspaces +% We want to swallow spaces (but not other tokens) after the fake +% @indent in our nonfill-environments, where spaces are normally +% active and set to @tie, resulting in them not being ignored after +% @indent. +\gdef\nonfillindent{\futurelet\temp\nonfillindentcheck}% +\gdef\nonfillindentcheck{% +\ifx\temp % +\expandafter\nonfillindentgobble% +\else% +\leavevmode\nonfillindentbox% +\fi% +}% +\endgroup +\def\nonfillindentgobble#1{\nonfillindent} +\def\nonfillindentbox{\hbox to \nonfillparindent{\hss}} + +% If you want all examples etc. small: @set dispenvsize small. +% If you want even small examples the full size: @set dispenvsize nosmall. +% This affects the following displayed environments: +% @example, @display, @format, @lisp +% +\def\smallword{small} +\def\nosmallword{nosmall} +\let\SETdispenvsize\relax +\def\setnormaldispenv{% + \ifx\SETdispenvsize\smallword + % end paragraph for sake of leading, in case document has no blank + % line. This is redundant with what happens in \aboveenvbreak, but + % we need to do it before changing the fonts, and it's inconvenient + % to change the fonts afterward. + \ifnum \lastpenalty=10000 \else \endgraf \fi + \smallexamplefonts \rm + \fi +} +\def\setsmalldispenv{% + \ifx\SETdispenvsize\nosmallword + \else + \ifnum \lastpenalty=10000 \else \endgraf \fi + \smallexamplefonts \rm + \fi +} + +% We often define two environments, @foo and @smallfoo. +% Let's do it in one command. #1 is the env name, #2 the definition. +\def\makedispenvdef#1#2{% + \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}% + \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}% + \expandafter\let\csname E#1\endcsname \afterenvbreak + \expandafter\let\csname Esmall#1\endcsname \afterenvbreak +} + +% Define two environment synonyms (#1 and #2) for an environment. +\def\maketwodispenvdef#1#2#3{% + \makedispenvdef{#1}{#3}% + \makedispenvdef{#2}{#3}% +} +% +% @lisp: indented, narrowed, typewriter font; +% @example: same as @lisp. +% +% @smallexample and @smalllisp: use smaller fonts. +% Originally contributed by Pavel@xerox. +% +\maketwodispenvdef{lisp}{example}{% + \nonfillstart + \tt\setupmarkupstyle{example}% + \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. + \gobble % eat return +} +% @display/@smalldisplay: same as @lisp except keep current font. +% +\makedispenvdef{display}{% + \nonfillstart + \gobble +} + +% @format/@smallformat: same as @display except don't narrow margins. +% +\makedispenvdef{format}{% + \let\nonarrowing = t% + \nonfillstart + \gobble +} + +% @flushleft: same as @format, but doesn't obey \SETdispenvsize. +\envdef\flushleft{% + \let\nonarrowing = t% + \nonfillstart + \gobble +} +\let\Eflushleft = \afterenvbreak + +% @flushright. +% +\envdef\flushright{% + \let\nonarrowing = t% + \nonfillstart + \advance\leftskip by 0pt plus 1fill\relax + \gobble +} +\let\Eflushright = \afterenvbreak + + +% @raggedright does more-or-less normal line breaking but no right +% justification. From plain.tex. +\envdef\raggedright{% + \rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax +} +\let\Eraggedright\par + +\envdef\raggedleft{% + \parindent=0pt \leftskip0pt plus2em + \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt + \hbadness=10000 % Last line will usually be underfull, so turn off + % badness reporting. +} +\let\Eraggedleft\par + +\envdef\raggedcenter{% + \parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em + \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt + \hbadness=10000 % Last line will usually be underfull, so turn off + % badness reporting. +} +\let\Eraggedcenter\par + + +% @quotation does normal linebreaking (hence we can't use \nonfillstart) +% and narrows the margins. We keep \parskip nonzero in general, since +% we're doing normal filling. So, when using \aboveenvbreak and +% \afterenvbreak, temporarily make \parskip 0. +% +\makedispenvdef{quotation}{\quotationstart} +% +\def\quotationstart{% + \indentedblockstart % same as \indentedblock, but increase right margin too. + \ifx\nonarrowing\relax + \advance\rightskip by \lispnarrowing + \fi + \parsearg\quotationlabel +} + +% We have retained a nonzero parskip for the environment, since we're +% doing normal filling. +% +\def\Equotation{% + \par + \ifx\quotationauthor\thisisundefined\else + % indent a bit. + \leftline{\kern 2\leftskip \sl ---\quotationauthor}% + \fi + {\parskip=0pt \afterenvbreak}% +} +\def\Esmallquotation{\Equotation} + +% If we're given an argument, typeset it in bold with a colon after. +\def\quotationlabel#1{% + \def\temp{#1}% + \ifx\temp\empty \else + {\bf #1: }% + \fi +} + +% @indentedblock is like @quotation, but indents only on the left and +% has no optional argument. +% +\makedispenvdef{indentedblock}{\indentedblockstart} +% +\def\indentedblockstart{% + {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip + \parindent=0pt + % + % @cartouche defines \nonarrowing to inhibit narrowing at next level down. + \ifx\nonarrowing\relax + \advance\leftskip by \lispnarrowing + \exdentamount = \lispnarrowing + \else + \let\nonarrowing = \relax + \fi +} + +% Keep a nonzero parskip for the environment, since we're doing normal filling. +% +\def\Eindentedblock{% + \par + {\parskip=0pt \afterenvbreak}% +} +\def\Esmallindentedblock{\Eindentedblock} + + +% LaTeX-like @verbatim...@end verbatim and @verb{...} +% If we want to allow any as delimiter, +% we need the curly braces so that makeinfo sees the @verb command, eg: +% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org +% +% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. +% +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. +\def\dospecials{% + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% + % Don't do the quotes -- if we do, @set txicodequoteundirected and + % @set txicodequotebacktick will not have effect on @verb and + % @verbatim, and ?` and !` ligatures won't get disabled. + %\do\`\do\'% +} +% +% [Knuth] p. 380 +\def\uncatcodespecials{% + \def\do##1{\catcode`##1=\other}\dospecials} +% +% Setup for the @verb command. +% +% Eight spaces for a tab +\begingroup + \catcode`\^^I=\active + \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} +\endgroup +% +\def\setupverb{% + \tt % easiest (and conventionally used) font for verbatim + \def\par{\leavevmode\endgraf}% + \setupmarkupstyle{verb}% + \tabeightspaces + % Respect line breaks, + % print special symbols as themselves, and + % make each space count + % must do in this order: + \obeylines \uncatcodespecials \sepspaces +} + +% Setup for the @verbatim environment +% +% Real tab expansion. +\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount +% +% We typeset each line of the verbatim in an \hbox, so we can handle +% tabs. The \global is in case the verbatim line starts with an accent, +% or some other command that starts with a begin-group. Otherwise, the +% entire \verbbox would disappear at the corresponding end-group, before +% it is typeset. Meanwhile, we can't have nested verbatim commands +% (can we?), so the \global won't be overwriting itself. +\newbox\verbbox +\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup} +% +\begingroup + \catcode`\^^I=\active + \gdef\tabexpand{% + \catcode`\^^I=\active + \def^^I{\leavevmode\egroup + \dimen\verbbox=\wd\verbbox % the width so far, or since the previous tab + \divide\dimen\verbbox by\tabw + \multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw + \advance\dimen\verbbox by\tabw % advance to next multiple of \tabw + \wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox + }% + } +\endgroup + +% start the verbatim environment. +\def\setupverbatim{% + \let\nonarrowing = t% + \nonfillstart + \tt % easiest (and conventionally used) font for verbatim + % The \leavevmode here is for blank lines. Otherwise, we would + % never \starttabox and the \egroup would end verbatim mode. + \def\par{\leavevmode\egroup\box\verbbox\endgraf}% + \tabexpand + \setupmarkupstyle{verbatim}% + % Respect line breaks, + % print special symbols as themselves, and + % make each space count. + % Must do in this order: + \obeylines \uncatcodespecials \sepspaces + \everypar{\starttabbox}% +} + +% Do the @verb magic: verbatim text is quoted by unique +% delimiter characters. Before first delimiter expect a +% right brace, after last delimiter expect closing brace: +% +% \def\doverb'{'#1'}'{#1} +% +% [Knuth] p. 382; only eat outer {} +\begingroup + \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other + \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] +\endgroup +% +\def\verb{\begingroup\setupverb\doverb} +% +% +% Do the @verbatim magic: define the macro \doverbatim so that +% the (first) argument ends when '@end verbatim' is reached, ie: +% +% \def\doverbatim#1@end verbatim{#1} +% +% For Texinfo it's a lot easier than for LaTeX, +% because texinfo's \verbatim doesn't stop at '\end{verbatim}': +% we need not redefine '\', '{' and '}'. +% +% Inspired by LaTeX's verbatim command set [latex.ltx] +% +\begingroup + \catcode`\ =\active + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% + % We really want {...\end verbatim} in the body of the macro, but + % without the active space; thus we have to use \xdef and \gobble. +\endgroup +% +\envdef\verbatim{% + \setupverbatim\doverbatim +} +\let\Everbatim = \afterenvbreak + + +% @verbatiminclude FILE - insert text of file in verbatim environment. +% +\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} +% +\def\doverbatiminclude#1{% + {% + \makevalueexpandable + \setupverbatim + \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% + \input #1 + \afterenvbreak + }% +} + +% @copying ... @end copying. +% Save the text away for @insertcopying later. +% +% We save the uninterpreted tokens, rather than creating a box. +% Saving the text in a box would be much easier, but then all the +% typesetting commands (@smallbook, font changes, etc.) have to be done +% beforehand -- and a) we want @copying to be done first in the source +% file; b) letting users define the frontmatter in as flexible order as +% possible is very desirable. +% +\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} +\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} +% +\def\insertcopying{% + \begingroup + \parindent = 0pt % paragraph indentation looks wrong on title page + \scanexp\copyingtext + \endgroup +} + + +\message{defuns,} +% @defun etc. + +\newskip\defbodyindent \defbodyindent=.4in +\newskip\defargsindent \defargsindent=50pt +\newskip\deflastargmargin \deflastargmargin=18pt +\newcount\defunpenalty + +% Start the processing of @deffn: +\def\startdefun{% + \ifnum\lastpenalty<10000 + \medbreak + \defunpenalty=10003 % Will keep this @deffn together with the + % following @def command, see below. + \else + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we need to allow a + % break somewhere. Check specifically for penalty 10002, inserted + % by \printdefunline, instead of 10000, since the sectioning + % commands also insert a nobreak penalty, and we don't want to allow + % a break between a section heading and a defun. + % + % As a further refinement, we avoid "club" headers by signalling + % with penalty of 10003 after the very first @deffn in the + % sequence (see above), and penalty of 10002 after any following + % @def command. + \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi + % + % Similarly, after a section heading, do not allow a break. + % But do insert the glue. + \medskip % preceded by discardable penalty, so not a breakpoint + \fi + % + \parindent=0in + \advance\leftskip by \defbodyindent + \exdentamount=\defbodyindent +} + +\def\dodefunx#1{% + % First, check whether we are in the right environment: + \checkenv#1% + % + % As above, allow line break if we have multiple x headers in a row. + % It's not a great place, though. + \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi + % + % And now, it's time to reuse the body of the original defun: + \expandafter\gobbledefun#1% +} +\def\gobbledefun#1\startdefun{} + +% \printdefunline \deffnheader{text} +% +\def\printdefunline#1#2{% + \begingroup + % call \deffnheader: + #1#2 \endheader + % common ending: + \interlinepenalty = 10000 + \advance\rightskip by 0pt plus 1fil\relax + \endgraf + \nobreak\vskip -\parskip + \penalty\defunpenalty % signal to \startdefun and \dodefunx + % Some of the @defun-type tags do not enable magic parentheses, + % rendering the following check redundant. But we don't optimize. + \checkparencounts + \endgroup +} + +\def\Edefun{\endgraf\medbreak} + +% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; +% the only thing remaining is to define \deffnheader. +% +\def\makedefun#1{% + \expandafter\let\csname E#1\endcsname = \Edefun + \edef\temp{\noexpand\domakedefun + \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% + \temp +} + +% \domakedefun \deffn \deffnx \deffnheader +% +% Define \deffn and \deffnx, without parameters. +% \deffnheader has to be defined explicitly. +% +\def\domakedefun#1#2#3{% + \envdef#1{% + \startdefun + \doingtypefnfalse % distinguish typed functions from all else + \parseargusing\activeparens{\printdefunline#3}% + }% + \def#2{\dodefunx#1}% + \def#3% +} + +\newif\ifdoingtypefn % doing typed function? +\newif\ifrettypeownline % typeset return type on its own line? + +% @deftypefnnewline on|off says whether the return type of typed functions +% are printed on their own line. This affects @deftypefn, @deftypefun, +% @deftypeop, and @deftypemethod. +% +\parseargdef\deftypefnnewline{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETtxideftypefnnl\endcsname + = \empty + \else\ifx\temp\offword + \expandafter\let\csname SETtxideftypefnnl\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @txideftypefnnl value `\temp', + must be on|off}% + \fi\fi +} + +% Untyped functions: + +% @deffn category name args +\makedefun{deffn}{\deffngeneral{}} + +% @deffn category class name args +\makedefun{defop}#1 {\defopon{#1\ \putwordon}} + +% \defopon {category on}class name args +\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } + +% \deffngeneral {subind}category name args +% +\def\deffngeneral#1#2 #3 #4\endheader{% + % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. + \dosubind{fn}{\code{#3}}{#1}% + \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% +} + +% Typed functions: + +% @deftypefn category type name args +\makedefun{deftypefn}{\deftypefngeneral{}} + +% @deftypeop category class type name args +\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} + +% \deftypeopon {category on}class type name args +\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } + +% \deftypefngeneral {subind}category type name args +% +\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% + \dosubind{fn}{\code{#4}}{#1}% + \doingtypefntrue + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% +} + +% Typed variables: + +% @deftypevr category type var args +\makedefun{deftypevr}{\deftypecvgeneral{}} + +% @deftypecv category class type var args +\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} + +% \deftypecvof {category of}class type var args +\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } + +% \deftypecvgeneral {subind}category type var args +% +\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% + \dosubind{vr}{\code{#4}}{#1}% + \defname{#2}{#3}{#4}\defunargs{#5\unskip}% +} + +% Untyped variables: + +% @defvr category var args +\makedefun{defvr}#1 {\deftypevrheader{#1} {} } + +% @defcv category class var args +\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} + +% \defcvof {category of}class var args +\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } + +% Types: + +% @deftp category name args +\makedefun{deftp}#1 #2 #3\endheader{% + \doind{tp}{\code{#2}}% + \defname{#1}{}{#2}\defunargs{#3\unskip}% +} + +% Remaining @defun-like shortcuts: +\makedefun{defun}{\deffnheader{\putwordDeffunc} } +\makedefun{defmac}{\deffnheader{\putwordDefmac} } +\makedefun{defspec}{\deffnheader{\putwordDefspec} } +\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } +\makedefun{defvar}{\defvrheader{\putwordDefvar} } +\makedefun{defopt}{\defvrheader{\putwordDefopt} } +\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } +\makedefun{defmethod}{\defopon\putwordMethodon} +\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} +\makedefun{defivar}{\defcvof\putwordInstanceVariableof} +\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} + +% \defname, which formats the name of the @def (not the args). +% #1 is the category, such as "Function". +% #2 is the return type, if any. +% #3 is the function name. +% +% We are followed by (but not passed) the arguments, if any. +% +\def\defname#1#2#3{% + \par + % Get the values of \leftskip and \rightskip as they were outside the @def... + \advance\leftskip by -\defbodyindent + % + % Determine if we are typesetting the return type of a typed function + % on a line by itself. + \rettypeownlinefalse + \ifdoingtypefn % doing a typed function specifically? + % then check user option for putting return type on its own line: + \expandafter\ifx\csname SETtxideftypefnnl\endcsname\relax \else + \rettypeownlinetrue + \fi + \fi + % + % How we'll format the category name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \def\temp{#1}% + \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} + % + % Figure out line sizes for the paragraph shape. We'll always have at + % least two. + \tempnum = 2 + % + % The first line needs space for \box0; but if \rightskip is nonzero, + % we need only space for the part of \box0 which exceeds it: + \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip + % + % If doing a return type on its own line, we'll have another line. + \ifrettypeownline + \advance\tempnum by 1 + \def\maybeshapeline{0in \hsize}% + \else + \def\maybeshapeline{}% + \fi + % + % The continuations: + \dimen2=\hsize \advance\dimen2 by -\defargsindent + % + % The final paragraph shape: + \parshape \tempnum 0in \dimen0 \maybeshapeline \defargsindent \dimen2 + % + % Put the category name at the right margin. + \noindent + \hbox to 0pt{% + \hfil\box0 \kern-\hsize + % \hsize has to be shortened this way: + \kern\leftskip + % Intentionally do not respect \rightskip, since we need the space. + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \exdentamount=\defbodyindent + {% + % defun fonts. We use typewriter by default (used to be bold) because: + % . we're printing identifiers, they should be in tt in principle. + % . in languages with many accents, such as Czech or French, it's + % common to leave accents off identifiers. The result looks ok in + % tt, but exceedingly strange in rm. + % . we don't want -- and --- to be treated as ligatures. + % . this still does not fix the ?` and !` ligatures, but so far no + % one has made identifiers using them :). + \df \tt + \def\temp{#2}% text of the return type + \ifx\temp\empty\else + \tclose{\temp}% typeset the return type + \ifrettypeownline + % put return type on its own line; prohibit line break following: + \hfil\vadjust{\nobreak}\break + \else + \space % type on same line, so just followed by a space + \fi + \fi % no return type + #3% output function name + }% + {\rm\enskip}% hskip 0.5 em of \tenrm + % + \boldbrax + % arguments will be output next, if any. +} + +% Print arguments in slanted roman (not ttsl), inconsistently with using +% tt for the name. This is because literal text is sometimes needed in +% the argument list (groff manual), and ttsl and tt are not very +% distinguishable. Prevent hyphenation at `-' chars. +% +\def\defunargs#1{% + % use sl by default (not ttsl), + % tt for the names. + \df \sl \hyphenchar\font=0 + % + % On the other hand, if an argument has two dashes (for instance), we + % want a way to get ttsl. We used to recommend @var for that, so + % leave the code in, but it's strange for @var to lead to typewriter. + % Nowadays we recommend @code, since the difference between a ttsl hyphen + % and a tt hyphen is pretty tiny. @code also disables ?` !`. + \def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}% + #1% + \sl\hyphenchar\font=45 +} + +% We want ()&[] to print specially on the defun line. +% +\def\activeparens{% + \catcode`\(=\active \catcode`\)=\active + \catcode`\[=\active \catcode`\]=\active + \catcode`\&=\active +} + +% Make control sequences which act like normal parenthesis chars. +\let\lparen = ( \let\rparen = ) + +% Be sure that we always have a definition for `(', etc. For example, +% if the fn name has parens in it, \boldbrax will not be in effect yet, +% so TeX would otherwise complain about undefined control sequence. +{ + \activeparens + \global\let(=\lparen \global\let)=\rparen + \global\let[=\lbrack \global\let]=\rbrack + \global\let& = \& + + \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} + \gdef\magicamp{\let&=\amprm} +} + +\newcount\parencount + +% If we encounter &foo, then turn on ()-hacking afterwards +\newif\ifampseen +\def\amprm#1 {\ampseentrue{\bf\ }} + +\def\parenfont{% + \ifampseen + % At the first level, print parens in roman, + % otherwise use the default font. + \ifnum \parencount=1 \rm \fi + \else + % The \sf parens (in \boldbrax) actually are a little bolder than + % the contained text. This is especially needed for [ and ] . + \sf + \fi +} +\def\infirstlevel#1{% + \ifampseen + \ifnum\parencount=1 + #1% + \fi + \fi +} +\def\bfafterword#1 {#1 \bf} + +\def\opnr{% + \global\advance\parencount by 1 + {\parenfont(}% + \infirstlevel \bfafterword +} +\def\clnr{% + {\parenfont)}% + \infirstlevel \sl + \global\advance\parencount by -1 +} + +\newcount\brackcount +\def\lbrb{% + \global\advance\brackcount by 1 + {\bf[}% +} +\def\rbrb{% + {\bf]}% + \global\advance\brackcount by -1 +} + +\def\checkparencounts{% + \ifnum\parencount=0 \else \badparencount \fi + \ifnum\brackcount=0 \else \badbrackcount \fi +} +% these should not use \errmessage; the glibc manual, at least, actually +% has such constructs (when documenting function pointers). +\def\badparencount{% + \message{Warning: unbalanced parentheses in @def...}% + \global\parencount=0 +} +\def\badbrackcount{% + \message{Warning: unbalanced square brackets in @def...}% + \global\brackcount=0 +} + + +\message{macros,} +% @macro. + +% To do this right we need a feature of e-TeX, \scantokens, +% which we arrange to emulate with a temporary file in ordinary TeX. +\ifx\eTeXversion\thisisundefined + \newwrite\macscribble + \def\scantokens#1{% + \toks0={#1}% + \immediate\openout\macscribble=\jobname.tmp + \immediate\write\macscribble{\the\toks0}% + \immediate\closeout\macscribble + \input \jobname.tmp + } +\fi + +\def\scanmacro#1{\begingroup + \newlinechar`\^^M + \let\xeatspaces\eatspaces + % + % Undo catcode changes of \startcontents and \doprintindex + % When called from @insertcopying or (short)caption, we need active + % backslash to get it printed correctly. Previously, we had + % \catcode`\\=\other instead. We'll see whether a problem appears + % with macro expansion. --kasal, 19aug04 + \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ + % + % ... and for \example: + \spaceisspace + % + % The \empty here causes a following catcode 5 newline to be eaten as + % part of reading whitespace after a control sequence. It does not + % eat a catcode 13 newline. There's no good way to handle the two + % cases (untried: maybe e-TeX's \everyeof could help, though plain TeX + % would then have different behavior). See the Macro Details node in + % the manual for the workaround we recommend for macros and + % line-oriented commands. + % + \scantokens{#1\empty}% +\endgroup} + +\def\scanexp#1{% + \edef\temp{\noexpand\scanmacro{#1}}% + \temp +} + +\newcount\paramno % Count of parameters +\newtoks\macname % Macro name +\newif\ifrecursive % Is it recursive? + +% List of all defined macros in the form +% \definedummyword\macro1\definedummyword\macro2... +% Currently is also contains all @aliases; the list can be split +% if there is a need. +\def\macrolist{} + +% Add the macro to \macrolist +\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} +\def\addtomacrolistxxx#1{% + \toks0 = \expandafter{\macrolist\definedummyword#1}% + \xdef\macrolist{\the\toks0}% +} + +% Utility routines. +% This does \let #1 = #2, with \csnames; that is, +% \let \csname#1\endcsname = \csname#2\endcsname +% (except of course we have to play expansion games). +% +\def\cslet#1#2{% + \expandafter\let + \csname#1\expandafter\endcsname + \csname#2\endcsname +} + +% Trim leading and trailing spaces off a string. +% Concepts from aro-bend problem 15 (see CTAN). +{\catcode`\@=11 +\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} +\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} +\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} +\def\unbrace#1{#1} +\unbrace{\gdef\trim@@@ #1 } #2@{#1} +} + +% Trim a single trailing ^^M off a string. +{\catcode`\^^M=\other \catcode`\Q=3% +\gdef\eatcr #1{\eatcra #1Q^^MQ}% +\gdef\eatcra#1^^MQ{\eatcrb#1Q}% +\gdef\eatcrb#1Q#2Q{#1}% +} + +% Macro bodies are absorbed as an argument in a context where +% all characters are catcode 10, 11 or 12, except \ which is active +% (as in normal texinfo). It is necessary to change the definition of \ +% to recognize macro arguments; this is the job of \mbodybackslash. +% +% Non-ASCII encodings make 8-bit characters active, so un-activate +% them to avoid their expansion. Must do this non-globally, to +% confine the change to the current group. +% +% It's necessary to have hard CRs when the macro is executed. This is +% done by making ^^M (\endlinechar) catcode 12 when reading the macro +% body, and then making it the \newlinechar in \scanmacro. +% +\def\scanctxt{% used as subroutine + \catcode`\"=\other + \catcode`\+=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\@=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\~=\other + \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi +} + +\def\scanargctxt{% used for copying and captions, not macros. + \scanctxt + \catcode`\\=\other + \catcode`\^^M=\other +} + +\def\macrobodyctxt{% used for @macro definitions + \scanctxt + \catcode`\{=\other + \catcode`\}=\other + \catcode`\^^M=\other + \usembodybackslash +} + +\def\macroargctxt{% used when scanning invocations + \scanctxt + \catcode`\\=0 +} +% why catcode 0 for \ in the above? To recognize \\ \{ \} as "escapes" +% for the single characters \ { }. Thus, we end up with the "commands" +% that would be written @\ @{ @} in a Texinfo document. +% +% We already have @{ and @}. For @\, we define it here, and only for +% this purpose, to produce a typewriter backslash (so, the @\ that we +% define for @math can't be used with @macro calls): +% +\def\\{\normalbackslash}% +% +% We would like to do this for \, too, since that is what makeinfo does. +% But it is not possible, because Texinfo already has a command @, for a +% cedilla accent. Documents must use @comma{} instead. +% +% \anythingelse will almost certainly be an error of some kind. + + +% \mbodybackslash is the definition of \ in @macro bodies. +% It maps \foo\ => \csname macarg.foo\endcsname => #N +% where N is the macro parameter number. +% We define \csname macarg.\endcsname to be \realbackslash, so +% \\ in macro replacement text gets you a backslash. +% +{\catcode`@=0 @catcode`@\=@active + @gdef@usembodybackslash{@let\=@mbodybackslash} + @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} +} +\expandafter\def\csname macarg.\endcsname{\realbackslash} + +\def\margbackslash#1{\char`\#1 } + +\def\macro{\recursivefalse\parsearg\macroxxx} +\def\rmacro{\recursivetrue\parsearg\macroxxx} + +\def\macroxxx#1{% + \getargs{#1}% now \macname is the macname and \argl the arglist + \ifx\argl\empty % no arguments + \paramno=0\relax + \else + \expandafter\parsemargdef \argl;% + \if\paramno>256\relax + \ifx\eTeXversion\thisisundefined + \errhelp = \EMsimple + \errmessage{You need eTeX to compile a file with macros with more than 256 arguments} + \fi + \fi + \fi + \if1\csname ismacro.\the\macname\endcsname + \message{Warning: redefining \the\macname}% + \else + \expandafter\ifx\csname \the\macname\endcsname \relax + \else \errmessage{Macro name \the\macname\space already defined}\fi + \global\cslet{macsave.\the\macname}{\the\macname}% + \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% + \addtomacrolist{\the\macname}% + \fi + \begingroup \macrobodyctxt + \ifrecursive \expandafter\parsermacbody + \else \expandafter\parsemacbody + \fi} + +\parseargdef\unmacro{% + \if1\csname ismacro.#1\endcsname + \global\cslet{#1}{macsave.#1}% + \global\expandafter\let \csname ismacro.#1\endcsname=0% + % Remove the macro name from \macrolist: + \begingroup + \expandafter\let\csname#1\endcsname \relax + \let\definedummyword\unmacrodo + \xdef\macrolist{\macrolist}% + \endgroup + \else + \errmessage{Macro #1 not defined}% + \fi +} + +% Called by \do from \dounmacro on each macro. The idea is to omit any +% macro definitions that have been changed to \relax. +% +\def\unmacrodo#1{% + \ifx #1\relax + % remove this + \else + \noexpand\definedummyword \noexpand#1% + \fi +} + +% This makes use of the obscure feature that if the last token of a +% is #, then the preceding argument is delimited by +% an opening brace, and that opening brace is not consumed. +\def\getargs#1{\getargsxxx#1{}} +\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} +\def\getmacname#1 #2\relax{\macname={#1}} +\def\getmacargs#1{\def\argl{#1}} + +% For macro processing make @ a letter so that we can make Texinfo private macro names. +\edef\texiatcatcode{\the\catcode`\@} +\catcode `@=11\relax + +% Parse the optional {params} list. Set up \paramno and \paramlist +% so \defmacro knows what to do. Define \macarg.BLAH for each BLAH +% in the params list to some hook where the argument si to be expanded. If +% there are less than 10 arguments that hook is to be replaced by ##N where N +% is the position in that list, that is to say the macro arguments are to be +% defined `a la TeX in the macro body. +% +% That gets used by \mbodybackslash (above). +% +% We need to get `macro parameter char #' into several definitions. +% The technique used is stolen from LaTeX: let \hash be something +% unexpandable, insert that wherever you need a #, and then redefine +% it to # just before using the token list produced. +% +% The same technique is used to protect \eatspaces till just before +% the macro is used. +% +% If there are 10 or more arguments, a different technique is used, where the +% hook remains in the body, and when macro is to be expanded the body is +% processed again to replace the arguments. +% +% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the +% argument N value and then \edef the body (nothing else will expand because of +% the catcode regime underwhich the body was input). +% +% If you compile with TeX (not eTeX), and you have macros with 10 or more +% arguments, you need that no macro has more than 256 arguments, otherwise an +% error is produced. +\def\parsemargdef#1;{% + \paramno=0\def\paramlist{}% + \let\hash\relax + \let\xeatspaces\relax + \parsemargdefxxx#1,;,% + % In case that there are 10 or more arguments we parse again the arguments + % list to set new definitions for the \macarg.BLAH macros corresponding to + % each BLAH argument. It was anyhow needed to parse already once this list + % in order to count the arguments, and as macros with at most 9 arguments + % are by far more frequent than macro with 10 or more arguments, defining + % twice the \macarg.BLAH macros does not cost too much processing power. + \ifnum\paramno<10\relax\else + \paramno0\relax + \parsemmanyargdef@@#1,;,% 10 or more arguments + \fi +} +\def\parsemargdefxxx#1,{% + \if#1;\let\next=\relax + \else \let\next=\parsemargdefxxx + \advance\paramno by 1 + \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname + {\xeatspaces{\hash\the\paramno}}% + \edef\paramlist{\paramlist\hash\the\paramno,}% + \fi\next} + +\def\parsemmanyargdef@@#1,{% + \if#1;\let\next=\relax + \else + \let\next=\parsemmanyargdef@@ + \edef\tempb{\eatspaces{#1}}% + \expandafter\def\expandafter\tempa + \expandafter{\csname macarg.\tempb\endcsname}% + % Note that we need some extra \noexpand\noexpand, this is because we + % don't want \the to be expanded in the \parsermacbody as it uses an + % \xdef . + \expandafter\edef\tempa + {\noexpand\noexpand\noexpand\the\toks\the\paramno}% + \advance\paramno by 1\relax + \fi\next} + +% These two commands read recursive and nonrecursive macro bodies. +% (They're different since rec and nonrec macros end differently.) +% + +\catcode `\@\texiatcatcode +\long\def\parsemacbody#1@end macro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% +\long\def\parsermacbody#1@end rmacro% +{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% +\catcode `\@=11\relax + +\let\endargs@\relax +\let\nil@\relax +\def\nilm@{\nil@}% +\long\def\nillm@{\nil@}% + +% This macro is expanded during the Texinfo macro expansion, not during its +% definition. It gets all the arguments values and assigns them to macros +% macarg.ARGNAME +% +% #1 is the macro name +% #2 is the list of argument names +% #3 is the list of argument values +\def\getargvals@#1#2#3{% + \def\macargdeflist@{}% + \def\saveparamlist@{#2}% Need to keep a copy for parameter expansion. + \def\paramlist{#2,\nil@}% + \def\macroname{#1}% + \begingroup + \macroargctxt + \def\argvaluelist{#3,\nil@}% + \def\@tempa{#3}% + \ifx\@tempa\empty + \setemptyargvalues@ + \else + \getargvals@@ + \fi +} + +% +\def\getargvals@@{% + \ifx\paramlist\nilm@ + % Some sanity check needed here that \argvaluelist is also empty. + \ifx\argvaluelist\nillm@ + \else + \errhelp = \EMsimple + \errmessage{Too many arguments in macro `\macroname'!}% + \fi + \let\next\macargexpandinbody@ + \else + \ifx\argvaluelist\nillm@ + % No more arguments values passed to macro. Set remaining named-arg + % macros to empty. + \let\next\setemptyargvalues@ + \else + % pop current arg name into \@tempb + \def\@tempa##1{\pop@{\@tempb}{\paramlist}##1\endargs@}% + \expandafter\@tempa\expandafter{\paramlist}% + % pop current argument value into \@tempc + \def\@tempa##1{\longpop@{\@tempc}{\argvaluelist}##1\endargs@}% + \expandafter\@tempa\expandafter{\argvaluelist}% + % Here \@tempb is the current arg name and \@tempc is the current arg value. + % First place the new argument macro definition into \@tempd + \expandafter\macname\expandafter{\@tempc}% + \expandafter\let\csname macarg.\@tempb\endcsname\relax + \expandafter\def\expandafter\@tempe\expandafter{% + \csname macarg.\@tempb\endcsname}% + \edef\@tempd{\long\def\@tempe{\the\macname}}% + \push@\@tempd\macargdeflist@ + \let\next\getargvals@@ + \fi + \fi + \next +} + +\def\push@#1#2{% + \expandafter\expandafter\expandafter\def + \expandafter\expandafter\expandafter#2% + \expandafter\expandafter\expandafter{% + \expandafter#1#2}% +} + +% Replace arguments by their values in the macro body, and place the result +% in macro \@tempa +\def\macvalstoargs@{% + % To do this we use the property that token registers that are \the'ed + % within an \edef expand only once. So we are going to place all argument + % values into respective token registers. + % + % First we save the token context, and initialize argument numbering. + \begingroup + \paramno0\relax + % Then, for each argument number #N, we place the corresponding argument + % value into a new token list register \toks#N + \expandafter\putargsintokens@\saveparamlist@,;,% + % Then, we expand the body so that argument are replaced by their + % values. The trick for values not to be expanded themselves is that they + % are within tokens and that tokens expand only once in an \edef . + \edef\@tempc{\csname mac.\macroname .body\endcsname}% + % Now we restore the token stack pointer to free the token list registers + % which we have used, but we make sure that expanded body is saved after + % group. + \expandafter + \endgroup + \expandafter\def\expandafter\@tempa\expandafter{\@tempc}% + } + +\def\macargexpandinbody@{% + %% Define the named-macro outside of this group and then close this group. + \expandafter + \endgroup + \macargdeflist@ + % First the replace in body the macro arguments by their values, the result + % is in \@tempa . + \macvalstoargs@ + % Then we point at the \norecurse or \gobble (for recursive) macro value + % with \@tempb . + \expandafter\let\expandafter\@tempb\csname mac.\macroname .recurse\endcsname + % Depending on whether it is recursive or not, we need some tailing + % \egroup . + \ifx\@tempb\gobble + \let\@tempc\relax + \else + \let\@tempc\egroup + \fi + % And now we do the real job: + \edef\@tempd{\noexpand\@tempb{\macroname}\noexpand\scanmacro{\@tempa}\@tempc}% + \@tempd +} + +\def\putargsintokens@#1,{% + \if#1;\let\next\relax + \else + \let\next\putargsintokens@ + % First we allocate the new token list register, and give it a temporary + % alias \@tempb . + \toksdef\@tempb\the\paramno + % Then we place the argument value into that token list register. + \expandafter\let\expandafter\@tempa\csname macarg.#1\endcsname + \expandafter\@tempb\expandafter{\@tempa}% + \advance\paramno by 1\relax + \fi + \next +} + +% Save the token stack pointer into macro #1 +\def\texisavetoksstackpoint#1{\edef#1{\the\@cclvi}} +% Restore the token stack pointer from number in macro #1 +\def\texirestoretoksstackpoint#1{\expandafter\mathchardef\expandafter\@cclvi#1\relax} +% newtoks that can be used non \outer . +\def\texinonouternewtoks{\alloc@ 5\toks \toksdef \@cclvi} + +% Tailing missing arguments are set to empty +\def\setemptyargvalues@{% + \ifx\paramlist\nilm@ + \let\next\macargexpandinbody@ + \else + \expandafter\setemptyargvaluesparser@\paramlist\endargs@ + \let\next\setemptyargvalues@ + \fi + \next +} + +\def\setemptyargvaluesparser@#1,#2\endargs@{% + \expandafter\def\expandafter\@tempa\expandafter{% + \expandafter\def\csname macarg.#1\endcsname{}}% + \push@\@tempa\macargdeflist@ + \def\paramlist{#2}% +} + +% #1 is the element target macro +% #2 is the list macro +% #3,#4\endargs@ is the list value +\def\pop@#1#2#3,#4\endargs@{% + \def#1{#3}% + \def#2{#4}% +} +\long\def\longpop@#1#2#3,#4\endargs@{% + \long\def#1{#3}% + \long\def#2{#4}% +} + +% This defines a Texinfo @macro. There are eight cases: recursive and +% nonrecursive macros of zero, one, up to nine, and many arguments. +% Much magic with \expandafter here. +% \xdef is used so that macro definitions will survive the file +% they're defined in; @include reads the file inside a group. +% +\def\defmacro{% + \let\hash=##% convert placeholders to macro parameter chars + \ifrecursive + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\scanmacro{\temp}}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup\noexpand\scanmacro{\temp}}% + \else + \ifnum\paramno<10\relax % at most 9 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{\egroup\noexpand\scanmacro{\temp}}% + \else % 10 or more + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\getargvals@{\the\macname}{\argl}% + }% + \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp + \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble + \fi + \fi + \else + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname xxx\endcsname}% + \expandafter\xdef\csname\the\macname xxx\endcsname##1{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \else % at most 9 + \ifnum\paramno<10\relax + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup\noexpand\macroargctxt + \expandafter\noexpand\csname\the\macname xx\endcsname}% + \expandafter\xdef\csname\the\macname xx\endcsname##1{% + \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname xxx\endcsname + \paramlist{% + \egroup + \noexpand\norecurse{\the\macname}% + \noexpand\scanmacro{\temp}\egroup}% + \else % 10 or more: + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\getargvals@{\the\macname}{\argl}% + }% + \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp + \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse + \fi + \fi + \fi} + +\catcode `\@\texiatcatcode\relax + +\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} + +% \braceorline decides whether the next nonwhitespace character is a +% {. If so it reads up to the closing }, if not, it reads the whole +% line. Whatever was read is then fed to the next control sequence +% as an argument (by \parsebrace or \parsearg). +% +\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} +\def\braceorlinexxx{% + \ifx\nchar\bgroup\else + \expandafter\parsearg + \fi \macnamexxx} + + +% @alias. +% We need some trickery to remove the optional spaces around the equal +% sign. Make them active and then expand them all to nothing. +% +\def\alias{\parseargusing\obeyspaces\aliasxxx} +\def\aliasxxx #1{\aliasyyy#1\relax} +\def\aliasyyy #1=#2\relax{% + {% + \expandafter\let\obeyedspace=\empty + \addtomacrolist{#1}% + \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% + }% + \next +} + + +\message{cross references,} + +\newwrite\auxfile +\newif\ifhavexrefs % True if xref values are known. +\newif\ifwarnedxrefs % True if we warned once that they aren't known. + +% @inforef is relatively simple. +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{% + \putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + +% @node's only job in TeX is to define \lastnode, which is used in +% cross-references. The @node line might or might not have commas, and +% might or might not have spaces before the first comma, like: +% @node foo , bar , ... +% We don't want such trailing spaces in the node name. +% +\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} +% +% also remove a trailing comma, in case of something like this: +% @node Help-Cross, , , Cross-refs +\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} +\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} + +\let\nwnode=\node +\let\lastnode=\empty + +% Write a cross-reference definition for the current node. #1 is the +% type (Ynumbered, Yappendix, Ynothing). +% +\def\donoderef#1{% + \ifx\lastnode\empty\else + \setref{\lastnode}{#1}% + \global\let\lastnode=\empty + \fi +} + +% @anchor{NAME} -- define xref target at arbitrary point. +% +\newcount\savesfregister +% +\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} +\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} +\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} + +% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an +% anchor), which consists of three parts: +% 1) NAME-title - the current sectioning name taken from \lastsection, +% or the anchor name. +% 2) NAME-snt - section number and type, passed as the SNT arg, or +% empty for anchors. +% 3) NAME-pg - the page number. +% +% This is called from \donoderef, \anchor, and \dofloat. In the case of +% floats, there is an additional part, which is not written here: +% 4) NAME-lof - the text as it should appear in a @listoffloats. +% +\def\setref#1#2{% + \pdfmkdest{#1}% + \iflinks + {% + \atdummies % preserve commands, but don't expand them + \edef\writexrdef##1##2{% + \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef + ##1}{##2}}% these are parameters of \writexrdef + }% + \toks0 = \expandafter{\lastsection}% + \immediate \writexrdef{title}{\the\toks0 }% + \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. + \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, at \shipout + }% + \fi +} + +% @xrefautosectiontitle on|off says whether @section(ing) names are used +% automatically in xrefs, if the third arg is not explicitly specified. +% This was provided as a "secret" @set xref-automatic-section-title +% variable, now it's official. +% +\parseargdef\xrefautomaticsectiontitle{% + \def\temp{#1}% + \ifx\temp\onword + \expandafter\let\csname SETxref-automatic-section-title\endcsname + = \empty + \else\ifx\temp\offword + \expandafter\let\csname SETxref-automatic-section-title\endcsname + = \relax + \else + \errhelp = \EMsimple + \errmessage{Unknown @xrefautomaticsectiontitle value `\temp', + must be on|off}% + \fi\fi +} + +% +% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is +% the node name, #2 the name of the Info cross-reference, #3 the printed +% node name, #4 the name of the Info file, #5 the name of the printed +% manual. All but the node name can be omitted. +% +\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} +\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} +\def\ref#1{\xrefX[#1,,,,,,,]} +% +\newbox\toprefbox +\newbox\printedrefnamebox +\newbox\infofilenamebox +\newbox\printedmanualbox +% +\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup + \unsepspaces + % + % Get args without leading/trailing spaces. + \def\printedrefname{\ignorespaces #3}% + \setbox\printedrefnamebox = \hbox{\printedrefname\unskip}% + % + \def\infofilename{\ignorespaces #4}% + \setbox\infofilenamebox = \hbox{\infofilename\unskip}% + % + \def\printedmanual{\ignorespaces #5}% + \setbox\printedmanualbox = \hbox{\printedmanual\unskip}% + % + % If the printed reference name (arg #3) was not explicitly given in + % the @xref, figure out what we want to use. + \ifdim \wd\printedrefnamebox = 0pt + % No printed node name was explicitly given. + \expandafter\ifx\csname SETxref-automatic-section-title\endcsname \relax + % Not auto section-title: use node name inside the square brackets. + \def\printedrefname{\ignorespaces #1}% + \else + % Auto section-title: use chapter/section title inside + % the square brackets if we have it. + \ifdim \wd\printedmanualbox > 0pt + % It is in another manual, so we don't have it; use node name. + \def\printedrefname{\ignorespaces #1}% + \else + \ifhavexrefs + % We (should) know the real title if we have the xref values. + \def\printedrefname{\refx{#1-title}{}}% + \else + % Otherwise just copy the Info node name. + \def\printedrefname{\ignorespaces #1}% + \fi% + \fi + \fi + \fi + % + % Make link in pdf output. + \ifpdf + {\indexnofonts + \turnoffactive + \makevalueexpandable + % This expands tokens, so do it after making catcode changes, so _ + % etc. don't get their TeX definitions. This ignores all spaces in + % #4, including (wrongly) those in the middle of the filename. + \getfilename{#4}% + % + % This (wrongly) does not take account of leading or trailing + % spaces in #1, which should be ignored. + \edef\pdfxrefdest{#1}% + \ifx\pdfxrefdest\empty + \def\pdfxrefdest{Top}% no empty targets + \else + \txiescapepdf\pdfxrefdest % escape PDF special chars + \fi + % + \leavevmode + \startlink attr{/Border [0 0 0]}% + \ifnum\filenamelength>0 + goto file{\the\filename.pdf} name{\pdfxrefdest}% + \else + goto name{\pdfmkpgn{\pdfxrefdest}}% + \fi + }% + \setcolor{\linkcolor}% + \fi + % + % Float references are printed completely differently: "Figure 1.2" + % instead of "[somenode], p.3". We distinguish them by the + % LABEL-title being set to a magic string. + {% + % Have to otherify everything special to allow the \csname to + % include an _ in the xref name, etc. + \indexnofonts + \turnoffactive + \expandafter\global\expandafter\let\expandafter\Xthisreftitle + \csname XR#1-title\endcsname + }% + \iffloat\Xthisreftitle + % If the user specified the print name (third arg) to the ref, + % print it instead of our usual "Figure 1.2". + \ifdim\wd\printedrefnamebox = 0pt + \refx{#1-snt}{}% + \else + \printedrefname + \fi + % + % If the user also gave the printed manual name (fifth arg), append + % "in MANUALNAME". + \ifdim \wd\printedmanualbox > 0pt + \space \putwordin{} \cite{\printedmanual}% + \fi + \else + % node/anchor (non-float) references. + % + % If we use \unhbox to print the node names, TeX does not insert + % empty discretionaries after hyphens, which means that it will not + % find a line break at a hyphen in a node names. Since some manuals + % are best written with fairly long node names, containing hyphens, + % this is a loss. Therefore, we give the text of the node name + % again, so it is as if TeX is seeing it for the first time. + % + \ifdim \wd\printedmanualbox > 0pt + % Cross-manual reference with a printed manual name. + % + \crossmanualxref{\cite{\printedmanual\unskip}}% + % + \else\ifdim \wd\infofilenamebox > 0pt + % Cross-manual reference with only an info filename (arg 4), no + % printed manual name (arg 5). This is essentially the same as + % the case above; we output the filename, since we have nothing else. + % + \crossmanualxref{\code{\infofilename\unskip}}% + % + \else + % Reference within this manual. + % + % _ (for example) has to be the character _ for the purposes of the + % control sequence corresponding to the node, but it has to expand + % into the usual \leavevmode...\vrule stuff for purposes of + % printing. So we \turnoffactive for the \refx-snt, back on for the + % printing, back off for the \refx-pg. + {\turnoffactive + % Only output a following space if the -snt ref is nonempty; for + % @unnumbered and @anchor, it won't be. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi + }% + % output the `[mynode]' via the macro below so it can be overridden. + \xrefprintnodename\printedrefname + % + % But we always want a comma and a space: + ,\space + % + % output the `page 3'. + \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \fi\fi + \fi + \endlink +\endgroup} + +% Output a cross-manual xref to #1. Used just above (twice). +% +% Only include the text "Section ``foo'' in" if the foo is neither +% missing or Top. Thus, @xref{,,,foo,The Foo Manual} outputs simply +% "see The Foo Manual", the idea being to refer to the whole manual. +% +% But, this being TeX, we can't easily compare our node name against the +% string "Top" while ignoring the possible spaces before and after in +% the input. By adding the arbitrary 7sp below, we make it much less +% likely that a real node name would have the same width as "Top" (e.g., +% in a monospaced font). Hopefully it will never happen in practice. +% +% For the same basic reason, we retypeset the "Top" at every +% reference, since the current font is indeterminate. +% +\def\crossmanualxref#1{% + \setbox\toprefbox = \hbox{Top\kern7sp}% + \setbox2 = \hbox{\ignorespaces \printedrefname \unskip \kern7sp}% + \ifdim \wd2 > 7sp % nonempty? + \ifdim \wd2 = \wd\toprefbox \else % same as Top? + \putwordSection{} ``\printedrefname'' \putwordin{}\space + \fi + \fi + #1% +} + +% This macro is called from \xrefX for the `[nodename]' part of xref +% output. It's a separate macro only so it can be changed more easily, +% since square brackets don't work well in some documents. Particularly +% one that Bob is working on :). +% +\def\xrefprintnodename#1{[#1]} + +% Things referred to by \setref. +% +\def\Ynothing{} +\def\Yomitfromtoc{} +\def\Ynumbered{% + \ifnum\secno=0 + \putwordChapter@tie \the\chapno + \else \ifnum\subsecno=0 + \putwordSection@tie \the\chapno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno + \else + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} +\def\Yappendix{% + \ifnum\secno=0 + \putwordAppendix@tie @char\the\appendixno{}% + \else \ifnum\subsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno + \else + \putwordSection@tie + @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} + +% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. +% If its value is nonempty, SUFFIX is output afterward. +% +\def\refx#1#2{% + {% + \indexnofonts + \otherbackslash + \expandafter\global\expandafter\let\expandafter\thisrefX + \csname XR#1\endcsname + }% + \ifx\thisrefX\relax + % If not defined, say something at least. + \angleleft un\-de\-fined\angleright + \iflinks + \ifhavexrefs + {\toks0 = {#1}% avoid expansion of possibly-complex value + \message{\linenumber Undefined cross reference `\the\toks0'.}}% + \else + \ifwarnedxrefs\else + \global\warnedxrefstrue + \message{Cross reference values unknown; you must run TeX again.}% + \fi + \fi + \fi + \else + % It's defined, so just use it. + \thisrefX + \fi + #2% Output the suffix in any case. +} + +% This is the macro invoked by entries in the aux file. Usually it's +% just a \def (we prepend XR to the control sequence name to avoid +% collisions). But if this is a float type, we have more work to do. +% +\def\xrdef#1#2{% + {% The node name might contain 8-bit characters, which in our current + % implementation are changed to commands like @'e. Don't let these + % mess up the control sequence name. + \indexnofonts + \turnoffactive + \xdef\safexrefname{#1}% + }% + % + \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref + % + % Was that xref control sequence that we just defined for a float? + \expandafter\iffloat\csname XR\safexrefname\endcsname + % it was a float, and we have the (safe) float type in \iffloattype. + \expandafter\let\expandafter\floatlist + \csname floatlist\iffloattype\endcsname + % + % Is this the first time we've seen this float type? + \expandafter\ifx\floatlist\relax + \toks0 = {\do}% yes, so just \do + \else + % had it before, so preserve previous elements in list. + \toks0 = \expandafter{\floatlist\do}% + \fi + % + % Remember this xref in the control sequence \floatlistFLOATTYPE, + % for later use in \listoffloats. + \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0 + {\safexrefname}}% + \fi +} + +% Read the last existing aux file, if any. No error if none exists. +% +\def\tryauxfile{% + \openin 1 \jobname.aux + \ifeof 1 \else + \readdatafile{aux}% + \global\havexrefstrue + \fi + \closein 1 +} + +\def\setupdatafile{% + \catcode`\^^@=\other + \catcode`\^^A=\other + \catcode`\^^B=\other + \catcode`\^^C=\other + \catcode`\^^D=\other + \catcode`\^^E=\other + \catcode`\^^F=\other + \catcode`\^^G=\other + \catcode`\^^H=\other + \catcode`\^^K=\other + \catcode`\^^L=\other + \catcode`\^^N=\other + \catcode`\^^P=\other + \catcode`\^^Q=\other + \catcode`\^^R=\other + \catcode`\^^S=\other + \catcode`\^^T=\other + \catcode`\^^U=\other + \catcode`\^^V=\other + \catcode`\^^W=\other + \catcode`\^^X=\other + \catcode`\^^Z=\other + \catcode`\^^[=\other + \catcode`\^^\=\other + \catcode`\^^]=\other + \catcode`\^^^=\other + \catcode`\^^_=\other + % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. + % in xref tags, i.e., node names. But since ^^e4 notation isn't + % supported in the main text, it doesn't seem desirable. Furthermore, + % that is not enough: for node names that actually contain a ^ + % character, we would end up writing a line like this: 'xrdef {'hat + % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first + % argument, and \hat is not an expandable control sequence. It could + % all be worked out, but why? Either we support ^^ or we don't. + % + % The other change necessary for this was to define \auxhat: + % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter + % and then to call \auxhat in \setq. + % + \catcode`\^=\other + % + % Special characters. Should be turned off anyway, but... + \catcode`\~=\other + \catcode`\[=\other + \catcode`\]=\other + \catcode`\"=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\$=\other + \catcode`\#=\other + \catcode`\&=\other + \catcode`\%=\other + \catcode`+=\other % avoid \+ for paranoia even though we've turned it off + % + % This is to support \ in node names and titles, since the \ + % characters end up in a \csname. It's easier than + % leaving it active and making its active definition an actual \ + % character. What I don't understand is why it works in the *value* + % of the xrdef. Seems like it should be a catcode12 \, and that + % should not typeset properly. But it works, so I'm moving on for + % now. --karl, 15jan04. + \catcode`\\=\other + % + % Make the characters 128-255 be printing characters. + {% + \count1=128 + \def\loop{% + \catcode\count1=\other + \advance\count1 by 1 + \ifnum \count1<256 \loop \fi + }% + }% + % + % @ is our escape character in .aux files, and we need braces. + \catcode`\{=1 + \catcode`\}=2 + \catcode`\@=0 +} + +\def\readdatafile#1{% +\begingroup + \setupdatafile + \input\jobname.#1 +\endgroup} + + +\message{insertions,} +% including footnotes. + +\newcount \footnoteno + +% The trailing space in the following definition for supereject is +% vital for proper filling; pages come out unaligned when you do a +% pagealignmacro call if that space before the closing brace is +% removed. (Generally, numeric constants should always be followed by a +% space to prevent strange expansion errors.) +\def\supereject{\par\penalty -20000\footnoteno =0 } + +% @footnotestyle is meaningful for Info output only. +\let\footnotestyle=\comment + +{\catcode `\@=11 +% +% Auto-number footnotes. Otherwise like plain. +\gdef\footnote{% + \let\indent=\ptexindent + \let\noindent=\ptexnoindent + \global\advance\footnoteno by \@ne + \edef\thisfootno{$^{\the\footnoteno}$}% + % + % In case the footnote comes at the end of a sentence, preserve the + % extra spacing after we do the footnote number. + \let\@sf\empty + \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi + % + % Remove inadvertent blank space before typesetting the footnote number. + \unskip + \thisfootno\@sf + \dofootnote +}% + +% Don't bother with the trickery in plain.tex to not require the +% footnote text as a parameter. Our footnotes don't need to be so general. +% +% Oh yes, they do; otherwise, @ifset (and anything else that uses +% \parseargline) fails inside footnotes because the tokens are fixed when +% the footnote is read. --karl, 16nov96. +% +\gdef\dofootnote{% + \insert\footins\bgroup + % We want to typeset this text as a normal paragraph, even if the + % footnote reference occurs in (for example) a display environment. + % So reset some parameters. + \hsize=\pagewidth + \interlinepenalty\interfootnotelinepenalty + \splittopskip\ht\strutbox % top baseline for broken footnotes + \splitmaxdepth\dp\strutbox + \floatingpenalty\@MM + \leftskip\z@skip + \rightskip\z@skip + \spaceskip\z@skip + \xspaceskip\z@skip + \parindent\defaultparindent + % + \smallfonts \rm + % + % Because we use hanging indentation in footnotes, a @noindent appears + % to exdent this text, so make it be a no-op. makeinfo does not use + % hanging indentation so @noindent can still be needed within footnote + % text after an @example or the like (not that this is good style). + \let\noindent = \relax + % + % Hang the footnote text off the number. Use \everypar in case the + % footnote extends for more than one paragraph. + \everypar = {\hang}% + \textindent{\thisfootno}% + % + % Don't crash into the line above the footnote text. Since this + % expands into a box, it must come within the paragraph, lest it + % provide a place where TeX can split the footnote. + \footstrut + % + % Invoke rest of plain TeX footnote routine. + \futurelet\next\fo@t +} +}%end \catcode `\@=11 + +% In case a @footnote appears in a vbox, save the footnote text and create +% the real \insert just after the vbox finished. Otherwise, the insertion +% would be lost. +% Similarly, if a @footnote appears inside an alignment, save the footnote +% text to a box and make the \insert when a row of the table is finished. +% And the same can be done for other insert classes. --kasal, 16nov03. + +% Replace the \insert primitive by a cheating macro. +% Deeper inside, just make sure that the saved insertions are not spilled +% out prematurely. +% +\def\startsavinginserts{% + \ifx \insert\ptexinsert + \let\insert\saveinsert + \else + \let\checkinserts\relax + \fi +} + +% This \insert replacement works for both \insert\footins{foo} and +% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. +% +\def\saveinsert#1{% + \edef\next{\noexpand\savetobox \makeSAVEname#1}% + \afterassignment\next + % swallow the left brace + \let\temp = +} +\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} +\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} + +\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} + +\def\placesaveins#1{% + \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname + {\box#1}% +} + +% eat @SAVE -- beware, all of them have catcode \other: +{ + \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) + \gdef\gobblesave @SAVE{} +} + +% initialization: +\def\newsaveins #1{% + \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% + \next +} +\def\newsaveinsX #1{% + \csname newbox\endcsname #1% + \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts + \checksaveins #1}% +} + +% initialize: +\let\checkinserts\empty +\newsaveins\footins +\newsaveins\margin + + +% @image. We use the macros from epsf.tex to support this. +% If epsf.tex is not installed and @image is used, we complain. +% +% Check for and read epsf.tex up front. If we read it only at @image +% time, we might be inside a group, and then its definitions would get +% undone and the next image would fail. +\openin 1 = epsf.tex +\ifeof 1 \else + % Do not bother showing banner with epsf.tex v2.7k (available in + % doc/epsf.tex and on ctan). + \def\epsfannounce{\toks0 = }% + \input epsf.tex +\fi +\closein 1 +% +% We will only complain once about lack of epsf.tex. +\newif\ifwarnednoepsf +\newhelp\noepsfhelp{epsf.tex must be installed for images to + work. It is also included in the Texinfo distribution, or you can get + it from ftp://tug.org/tex/epsf.tex.} +% +\def\image#1{% + \ifx\epsfbox\thisisundefined + \ifwarnednoepsf \else + \errhelp = \noepsfhelp + \errmessage{epsf.tex not found, images will be ignored}% + \global\warnednoepsftrue + \fi + \else + \imagexxx #1,,,,,\finish + \fi +} +% +% Arguments to @image: +% #1 is (mandatory) image filename; we tack on .eps extension. +% #2 is (optional) width, #3 is (optional) height. +% #4 is (ignored optional) html alt text. +% #5 is (ignored optional) extension. +% #6 is just the usual extra ignored arg for parsing stuff. +\newif\ifimagevmode +\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup + \catcode`\^^M = 5 % in case we're inside an example + \normalturnoffactive % allow _ et al. in names + % If the image is by itself, center it. + \ifvmode + \imagevmodetrue + \else \ifx\centersub\centerV + % for @center @image, we need a vbox so we can have our vertical space + \imagevmodetrue + \vbox\bgroup % vbox has better behavior than vtop herev + \fi\fi + % + \ifimagevmode + \nobreak\medskip + % Usually we'll have text after the image which will insert + % \parskip glue, so insert it here too to equalize the space + % above and below. + \nobreak\vskip\parskip + \nobreak + \fi + % + % Leave vertical mode so that indentation from an enclosing + % environment such as @quotation is respected. + % However, if we're at the top level, we don't want the + % normal paragraph indentation. + % On the other hand, if we are in the case of @center @image, we don't + % want to start a paragraph, which will create a hsize-width box and + % eradicate the centering. + \ifx\centersub\centerV\else \noindent \fi + % + % Output the image. + \ifpdf + \dopdfimage{#1}{#2}{#3}% + \else + % \epsfbox itself resets \epsf?size at each figure. + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi + \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi + \epsfbox{#1.eps}% + \fi + % + \ifimagevmode + \medskip % space after a standalone image + \fi + \ifx\centersub\centerV \egroup \fi +\endgroup} + + +% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, +% etc. We don't actually implement floating yet, we always include the +% float "here". But it seemed the best name for the future. +% +\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} + +% There may be a space before second and/or third parameter; delete it. +\def\eatcommaspace#1, {#1,} + +% #1 is the optional FLOATTYPE, the text label for this float, typically +% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, +% this float will not be numbered and cannot be referred to. +% +% #2 is the optional xref label. Also must be present for the float to +% be referable. +% +% #3 is the optional positioning argument; for now, it is ignored. It +% will somehow specify the positions allowed to float to (here, top, bottom). +% +% We keep a separate counter for each FLOATTYPE, which we reset at each +% chapter-level command. +\let\resetallfloatnos=\empty +% +\def\dofloat#1,#2,#3,#4\finish{% + \let\thiscaption=\empty + \let\thisshortcaption=\empty + % + % don't lose footnotes inside @float. + % + % BEWARE: when the floats start float, we have to issue warning whenever an + % insert appears inside a float which could possibly float. --kasal, 26may04 + % + \startsavinginserts + % + % We can't be used inside a paragraph. + \par + % + \vtop\bgroup + \def\floattype{#1}% + \def\floatlabel{#2}% + \def\floatloc{#3}% we do nothing with this yet. + % + \ifx\floattype\empty + \let\safefloattype=\empty + \else + {% + % the floattype might have accents or other special characters, + % but we need to use it in a control sequence name. + \indexnofonts + \turnoffactive + \xdef\safefloattype{\floattype}% + }% + \fi + % + % If label is given but no type, we handle that as the empty type. + \ifx\floatlabel\empty \else + % We want each FLOATTYPE to be numbered separately (Figure 1, + % Table 1, Figure 2, ...). (And if no label, no number.) + % + \expandafter\getfloatno\csname\safefloattype floatno\endcsname + \global\advance\floatno by 1 + % + {% + % This magic value for \lastsection is output by \setref as the + % XREFLABEL-title value. \xrefX uses it to distinguish float + % labels (which have a completely different output format) from + % node and anchor labels. And \xrdef uses it to construct the + % lists of floats. + % + \edef\lastsection{\floatmagic=\safefloattype}% + \setref{\floatlabel}{Yfloat}% + }% + \fi + % + % start with \parskip glue, I guess. + \vskip\parskip + % + % Don't suppress indentation if a float happens to start a section. + \restorefirstparagraphindent +} + +% we have these possibilities: +% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap +% @float Foo,lbl & no caption: Foo 1.1 +% @float Foo & @caption{Cap}: Foo: Cap +% @float Foo & no caption: Foo +% @float ,lbl & Caption{Cap}: 1.1: Cap +% @float ,lbl & no caption: 1.1 +% @float & @caption{Cap}: Cap +% @float & no caption: +% +\def\Efloat{% + \let\floatident = \empty + % + % In all cases, if we have a float type, it comes first. + \ifx\floattype\empty \else \def\floatident{\floattype}\fi + % + % If we have an xref label, the number comes next. + \ifx\floatlabel\empty \else + \ifx\floattype\empty \else % if also had float type, need tie first. + \appendtomacro\floatident{\tie}% + \fi + % the number. + \appendtomacro\floatident{\chaplevelprefix\the\floatno}% + \fi + % + % Start the printed caption with what we've constructed in + % \floatident, but keep it separate; we need \floatident again. + \let\captionline = \floatident + % + \ifx\thiscaption\empty \else + \ifx\floatident\empty \else + \appendtomacro\captionline{: }% had ident, so need a colon between + \fi + % + % caption text. + \appendtomacro\captionline{\scanexp\thiscaption}% + \fi + % + % If we have anything to print, print it, with space before. + % Eventually this needs to become an \insert. + \ifx\captionline\empty \else + \vskip.5\parskip + \captionline + % + % Space below caption. + \vskip\parskip + \fi + % + % If have an xref label, write the list of floats info. Do this + % after the caption, to avoid chance of it being a breakpoint. + \ifx\floatlabel\empty \else + % Write the text that goes in the lof to the aux file as + % \floatlabel-lof. Besides \floatident, we include the short + % caption if specified, else the full caption if specified, else nothing. + {% + \atdummies + % + % since we read the caption text in the macro world, where ^^M + % is turned into a normal character, we have to scan it back, so + % we don't write the literal three characters "^^M" into the aux file. + \scanexp{% + \xdef\noexpand\gtemp{% + \ifx\thisshortcaption\empty + \thiscaption + \else + \thisshortcaption + \fi + }% + }% + \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident + \ifx\gtemp\empty \else : \gtemp \fi}}% + }% + \fi + \egroup % end of \vtop + % + % place the captured inserts + % + % BEWARE: when the floats start floating, we have to issue warning + % whenever an insert appears inside a float which could possibly + % float. --kasal, 26may04 + % + \checkinserts +} + +% Append the tokens #2 to the definition of macro #1, not expanding either. +% +\def\appendtomacro#1#2{% + \expandafter\def\expandafter#1\expandafter{#1#2}% +} + +% @caption, @shortcaption +% +\def\caption{\docaption\thiscaption} +\def\shortcaption{\docaption\thisshortcaption} +\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} +\def\defcaption#1#2{\egroup \def#1{#2}} + +% The parameter is the control sequence identifying the counter we are +% going to use. Create it if it doesn't exist and assign it to \floatno. +\def\getfloatno#1{% + \ifx#1\relax + % Haven't seen this figure type before. + \csname newcount\endcsname #1% + % + % Remember to reset this floatno at the next chap. + \expandafter\gdef\expandafter\resetallfloatnos + \expandafter{\resetallfloatnos #1=0 }% + \fi + \let\floatno#1% +} + +% \setref calls this to get the XREFLABEL-snt value. We want an @xref +% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we +% first read the @float command. +% +\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% + +% Magic string used for the XREFLABEL-title value, so \xrefX can +% distinguish floats from other xref types. +\def\floatmagic{!!float!!} + +% #1 is the control sequence we are passed; we expand into a conditional +% which is true if #1 represents a float ref. That is, the magic +% \lastsection value which we \setref above. +% +\def\iffloat#1{\expandafter\doiffloat#1==\finish} +% +% #1 is (maybe) the \floatmagic string. If so, #2 will be the +% (safe) float type for this float. We set \iffloattype to #2. +% +\def\doiffloat#1=#2=#3\finish{% + \def\temp{#1}% + \def\iffloattype{#2}% + \ifx\temp\floatmagic +} + +% @listoffloats FLOATTYPE - print a list of floats like a table of contents. +% +\parseargdef\listoffloats{% + \def\floattype{#1}% floattype + {% + % the floattype might have accents or other special characters, + % but we need to use it in a control sequence name. + \indexnofonts + \turnoffactive + \xdef\safefloattype{\floattype}% + }% + % + % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. + \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax + \ifhavexrefs + % if the user said @listoffloats foo but never @float foo. + \message{\linenumber No `\safefloattype' floats to list.}% + \fi + \else + \begingroup + \leftskip=\tocindent % indent these entries like a toc + \let\do=\listoffloatsdo + \csname floatlist\safefloattype\endcsname + \endgroup + \fi +} + +% This is called on each entry in a list of floats. We're passed the +% xref label, in the form LABEL-title, which is how we save it in the +% aux file. We strip off the -title and look up \XRLABEL-lof, which +% has the text we're supposed to typeset here. +% +% Figures without xref labels will not be included in the list (since +% they won't appear in the aux file). +% +\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} +\def\listoffloatsdoentry#1-title\finish{{% + % Can't fully expand XR#1-lof because it can contain anything. Just + % pass the control sequence. On the other hand, XR#1-pg is just the + % page number, and we want to fully expand that so we can get a link + % in pdf output. + \toksA = \expandafter{\csname XR#1-lof\endcsname}% + % + % use the same \entry macro we use to generate the TOC and index. + \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% + \writeentry +}} + + +\message{localization,} + +% For single-language documents, @documentlanguage is usually given very +% early, just after @documentencoding. Single argument is the language +% (de) or locale (de_DE) abbreviation. +% +{ + \catcode`\_ = \active + \globaldefs=1 +\parseargdef\documentlanguage{\begingroup + \let_=\normalunderscore % normal _ character for filenames + \tex % read txi-??.tex file in plain TeX. + % Read the file by the name they passed if it exists. + \openin 1 txi-#1.tex + \ifeof 1 + \documentlanguagetrywithoutunderscore{#1_\finish}% + \else + \globaldefs = 1 % everything in the txi-LL files needs to persist + \input txi-#1.tex + \fi + \closein 1 + \endgroup % end raw TeX +\endgroup} +% +% If they passed de_DE, and txi-de_DE.tex doesn't exist, +% try txi-de.tex. +% +\gdef\documentlanguagetrywithoutunderscore#1_#2\finish{% + \openin 1 txi-#1.tex + \ifeof 1 + \errhelp = \nolanghelp + \errmessage{Cannot read language file txi-#1.tex}% + \else + \globaldefs = 1 % everything in the txi-LL files needs to persist + \input txi-#1.tex + \fi + \closein 1 +} +}% end of special _ catcode +% +\newhelp\nolanghelp{The given language definition file cannot be found or +is empty. Maybe you need to install it? Putting it in the current +directory should work if nowhere else does.} + +% This macro is called from txi-??.tex files; the first argument is the +% \language name to set (without the "\lang@" prefix), the second and +% third args are \{left,right}hyphenmin. +% +% The language names to pass are determined when the format is built. +% See the etex.log file created at that time, e.g., +% /usr/local/texlive/2008/texmf-var/web2c/pdftex/etex.log. +% +% With TeX Live 2008, etex now includes hyphenation patterns for all +% available languages. This means we can support hyphenation in +% Texinfo, at least to some extent. (This still doesn't solve the +% accented characters problem.) +% +\catcode`@=11 +\def\txisetlanguage#1#2#3{% + % do not set the language if the name is undefined in the current TeX. + \expandafter\ifx\csname lang@#1\endcsname \relax + \message{no patterns for #1}% + \else + \global\language = \csname lang@#1\endcsname + \fi + % but there is no harm in adjusting the hyphenmin values regardless. + \global\lefthyphenmin = #2\relax + \global\righthyphenmin = #3\relax +} + +% Helpers for encodings. +% Set the catcode of characters 128 through 255 to the specified number. +% +\def\setnonasciicharscatcode#1{% + \count255=128 + \loop\ifnum\count255<256 + \global\catcode\count255=#1\relax + \advance\count255 by 1 + \repeat +} + +\def\setnonasciicharscatcodenonglobal#1{% + \count255=128 + \loop\ifnum\count255<256 + \catcode\count255=#1\relax + \advance\count255 by 1 + \repeat +} + +% @documentencoding sets the definition of non-ASCII characters +% according to the specified encoding. +% +\parseargdef\documentencoding{% + % Encoding being declared for the document. + \def\declaredencoding{\csname #1.enc\endcsname}% + % + % Supported encodings: names converted to tokens in order to be able + % to compare them with \ifx. + \def\ascii{\csname US-ASCII.enc\endcsname}% + \def\latnine{\csname ISO-8859-15.enc\endcsname}% + \def\latone{\csname ISO-8859-1.enc\endcsname}% + \def\lattwo{\csname ISO-8859-2.enc\endcsname}% + \def\utfeight{\csname UTF-8.enc\endcsname}% + % + \ifx \declaredencoding \ascii + \asciichardefs + % + \else \ifx \declaredencoding \lattwo + \setnonasciicharscatcode\active + \lattwochardefs + % + \else \ifx \declaredencoding \latone + \setnonasciicharscatcode\active + \latonechardefs + % + \else \ifx \declaredencoding \latnine + \setnonasciicharscatcode\active + \latninechardefs + % + \else \ifx \declaredencoding \utfeight + \setnonasciicharscatcode\active + \utfeightchardefs + % + \else + \message{Unknown document encoding #1, ignoring.}% + % + \fi % utfeight + \fi % latnine + \fi % latone + \fi % lattwo + \fi % ascii +} + +% A message to be logged when using a character that isn't available +% the default font encoding (OT1). +% +\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} + +% Take account of \c (plain) vs. \, (Texinfo) difference. +\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} + +% First, make active non-ASCII characters in order for them to be +% correctly categorized when TeX reads the replacement text of +% macros containing the character definitions. +\setnonasciicharscatcode\active +% +% Latin1 (ISO-8859-1) character definitions. +\def\latonechardefs{% + \gdef^^a0{\tie} + \gdef^^a1{\exclamdown} + \gdef^^a2{\missingcharmsg{CENT SIGN}} + \gdef^^a3{{\pounds}} + \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} + \gdef^^a5{\missingcharmsg{YEN SIGN}} + \gdef^^a6{\missingcharmsg{BROKEN BAR}} + \gdef^^a7{\S} + \gdef^^a8{\"{}} + \gdef^^a9{\copyright} + \gdef^^aa{\ordf} + \gdef^^ab{\guillemetleft} + \gdef^^ac{$\lnot$} + \gdef^^ad{\-} + \gdef^^ae{\registeredsymbol} + \gdef^^af{\={}} + % + \gdef^^b0{\textdegree} + \gdef^^b1{$\pm$} + \gdef^^b2{$^2$} + \gdef^^b3{$^3$} + \gdef^^b4{\'{}} + \gdef^^b5{$\mu$} + \gdef^^b6{\P} + % + \gdef^^b7{$^.$} + \gdef^^b8{\cedilla\ } + \gdef^^b9{$^1$} + \gdef^^ba{\ordm} + % + \gdef^^bb{\guillemetright} + \gdef^^bc{$1\over4$} + \gdef^^bd{$1\over2$} + \gdef^^be{$3\over4$} + \gdef^^bf{\questiondown} + % + \gdef^^c0{\`A} + \gdef^^c1{\'A} + \gdef^^c2{\^A} + \gdef^^c3{\~A} + \gdef^^c4{\"A} + \gdef^^c5{\ringaccent A} + \gdef^^c6{\AE} + \gdef^^c7{\cedilla C} + \gdef^^c8{\`E} + \gdef^^c9{\'E} + \gdef^^ca{\^E} + \gdef^^cb{\"E} + \gdef^^cc{\`I} + \gdef^^cd{\'I} + \gdef^^ce{\^I} + \gdef^^cf{\"I} + % + \gdef^^d0{\DH} + \gdef^^d1{\~N} + \gdef^^d2{\`O} + \gdef^^d3{\'O} + \gdef^^d4{\^O} + \gdef^^d5{\~O} + \gdef^^d6{\"O} + \gdef^^d7{$\times$} + \gdef^^d8{\O} + \gdef^^d9{\`U} + \gdef^^da{\'U} + \gdef^^db{\^U} + \gdef^^dc{\"U} + \gdef^^dd{\'Y} + \gdef^^de{\TH} + \gdef^^df{\ss} + % + \gdef^^e0{\`a} + \gdef^^e1{\'a} + \gdef^^e2{\^a} + \gdef^^e3{\~a} + \gdef^^e4{\"a} + \gdef^^e5{\ringaccent a} + \gdef^^e6{\ae} + \gdef^^e7{\cedilla c} + \gdef^^e8{\`e} + \gdef^^e9{\'e} + \gdef^^ea{\^e} + \gdef^^eb{\"e} + \gdef^^ec{\`{\dotless i}} + \gdef^^ed{\'{\dotless i}} + \gdef^^ee{\^{\dotless i}} + \gdef^^ef{\"{\dotless i}} + % + \gdef^^f0{\dh} + \gdef^^f1{\~n} + \gdef^^f2{\`o} + \gdef^^f3{\'o} + \gdef^^f4{\^o} + \gdef^^f5{\~o} + \gdef^^f6{\"o} + \gdef^^f7{$\div$} + \gdef^^f8{\o} + \gdef^^f9{\`u} + \gdef^^fa{\'u} + \gdef^^fb{\^u} + \gdef^^fc{\"u} + \gdef^^fd{\'y} + \gdef^^fe{\th} + \gdef^^ff{\"y} +} + +% Latin9 (ISO-8859-15) encoding character definitions. +\def\latninechardefs{% + % Encoding is almost identical to Latin1. + \latonechardefs + % + \gdef^^a4{\euro} + \gdef^^a6{\v S} + \gdef^^a8{\v s} + \gdef^^b4{\v Z} + \gdef^^b8{\v z} + \gdef^^bc{\OE} + \gdef^^bd{\oe} + \gdef^^be{\"Y} +} + +% Latin2 (ISO-8859-2) character definitions. +\def\lattwochardefs{% + \gdef^^a0{\tie} + \gdef^^a1{\ogonek{A}} + \gdef^^a2{\u{}} + \gdef^^a3{\L} + \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} + \gdef^^a5{\v L} + \gdef^^a6{\'S} + \gdef^^a7{\S} + \gdef^^a8{\"{}} + \gdef^^a9{\v S} + \gdef^^aa{\cedilla S} + \gdef^^ab{\v T} + \gdef^^ac{\'Z} + \gdef^^ad{\-} + \gdef^^ae{\v Z} + \gdef^^af{\dotaccent Z} + % + \gdef^^b0{\textdegree} + \gdef^^b1{\ogonek{a}} + \gdef^^b2{\ogonek{ }} + \gdef^^b3{\l} + \gdef^^b4{\'{}} + \gdef^^b5{\v l} + \gdef^^b6{\'s} + \gdef^^b7{\v{}} + \gdef^^b8{\cedilla\ } + \gdef^^b9{\v s} + \gdef^^ba{\cedilla s} + \gdef^^bb{\v t} + \gdef^^bc{\'z} + \gdef^^bd{\H{}} + \gdef^^be{\v z} + \gdef^^bf{\dotaccent z} + % + \gdef^^c0{\'R} + \gdef^^c1{\'A} + \gdef^^c2{\^A} + \gdef^^c3{\u A} + \gdef^^c4{\"A} + \gdef^^c5{\'L} + \gdef^^c6{\'C} + \gdef^^c7{\cedilla C} + \gdef^^c8{\v C} + \gdef^^c9{\'E} + \gdef^^ca{\ogonek{E}} + \gdef^^cb{\"E} + \gdef^^cc{\v E} + \gdef^^cd{\'I} + \gdef^^ce{\^I} + \gdef^^cf{\v D} + % + \gdef^^d0{\DH} + \gdef^^d1{\'N} + \gdef^^d2{\v N} + \gdef^^d3{\'O} + \gdef^^d4{\^O} + \gdef^^d5{\H O} + \gdef^^d6{\"O} + \gdef^^d7{$\times$} + \gdef^^d8{\v R} + \gdef^^d9{\ringaccent U} + \gdef^^da{\'U} + \gdef^^db{\H U} + \gdef^^dc{\"U} + \gdef^^dd{\'Y} + \gdef^^de{\cedilla T} + \gdef^^df{\ss} + % + \gdef^^e0{\'r} + \gdef^^e1{\'a} + \gdef^^e2{\^a} + \gdef^^e3{\u a} + \gdef^^e4{\"a} + \gdef^^e5{\'l} + \gdef^^e6{\'c} + \gdef^^e7{\cedilla c} + \gdef^^e8{\v c} + \gdef^^e9{\'e} + \gdef^^ea{\ogonek{e}} + \gdef^^eb{\"e} + \gdef^^ec{\v e} + \gdef^^ed{\'{\dotless{i}}} + \gdef^^ee{\^{\dotless{i}}} + \gdef^^ef{\v d} + % + \gdef^^f0{\dh} + \gdef^^f1{\'n} + \gdef^^f2{\v n} + \gdef^^f3{\'o} + \gdef^^f4{\^o} + \gdef^^f5{\H o} + \gdef^^f6{\"o} + \gdef^^f7{$\div$} + \gdef^^f8{\v r} + \gdef^^f9{\ringaccent u} + \gdef^^fa{\'u} + \gdef^^fb{\H u} + \gdef^^fc{\"u} + \gdef^^fd{\'y} + \gdef^^fe{\cedilla t} + \gdef^^ff{\dotaccent{}} +} + +% UTF-8 character definitions. +% +% This code to support UTF-8 is based on LaTeX's utf8.def, with some +% changes for Texinfo conventions. It is included here under the GPL by +% permission from Frank Mittelbach and the LaTeX team. +% +\newcount\countUTFx +\newcount\countUTFy +\newcount\countUTFz + +\gdef\UTFviiiTwoOctets#1#2{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\endcsname} +% +\gdef\UTFviiiThreeOctets#1#2#3{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname} +% +\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter + \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname} + +\gdef\UTFviiiDefined#1{% + \ifx #1\relax + \message{\linenumber Unicode char \string #1 not defined for Texinfo}% + \else + \expandafter #1% + \fi +} + +\begingroup + \catcode`\~13 + \catcode`\"12 + + \def\UTFviiiLoop{% + \global\catcode\countUTFx\active + \uccode`\~\countUTFx + \uppercase\expandafter{\UTFviiiTmp}% + \advance\countUTFx by 1 + \ifnum\countUTFx < \countUTFy + \expandafter\UTFviiiLoop + \fi} + + \countUTFx = "C2 + \countUTFy = "E0 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiTwoOctets\string~}} + \UTFviiiLoop + + \countUTFx = "E0 + \countUTFy = "F0 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiThreeOctets\string~}} + \UTFviiiLoop + + \countUTFx = "F0 + \countUTFy = "F4 + \def\UTFviiiTmp{% + \xdef~{\noexpand\UTFviiiFourOctets\string~}} + \UTFviiiLoop +\endgroup + +\begingroup + \catcode`\"=12 + \catcode`\<=12 + \catcode`\.=12 + \catcode`\,=12 + \catcode`\;=12 + \catcode`\!=12 + \catcode`\~=13 + + \gdef\DeclareUnicodeCharacter#1#2{% + \countUTFz = "#1\relax + %\wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% + \begingroup + \parseXMLCharref + \def\UTFviiiTwoOctets##1##2{% + \csname u8:##1\string ##2\endcsname}% + \def\UTFviiiThreeOctets##1##2##3{% + \csname u8:##1\string ##2\string ##3\endcsname}% + \def\UTFviiiFourOctets##1##2##3##4{% + \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter + \gdef\UTFviiiTmp{#2}% + \endgroup} + + \gdef\parseXMLCharref{% + \ifnum\countUTFz < "A0\relax + \errhelp = \EMsimple + \errmessage{Cannot define Unicode char value < 00A0}% + \else\ifnum\countUTFz < "800\relax + \parseUTFviiiA,% + \parseUTFviiiB C\UTFviiiTwoOctets.,% + \else\ifnum\countUTFz < "10000\relax + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% + \else + \parseUTFviiiA;% + \parseUTFviiiA,% + \parseUTFviiiA!% + \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% + \fi\fi\fi + } + + \gdef\parseUTFviiiA#1{% + \countUTFx = \countUTFz + \divide\countUTFz by 64 + \countUTFy = \countUTFz + \multiply\countUTFz by 64 + \advance\countUTFx by -\countUTFz + \advance\countUTFx by 128 + \uccode `#1\countUTFx + \countUTFz = \countUTFy} + + \gdef\parseUTFviiiB#1#2#3#4{% + \advance\countUTFz by "#10\relax + \uccode `#3\countUTFz + \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} +\endgroup + +\def\utfeightchardefs{% + \DeclareUnicodeCharacter{00A0}{\tie} + \DeclareUnicodeCharacter{00A1}{\exclamdown} + \DeclareUnicodeCharacter{00A3}{\pounds} + \DeclareUnicodeCharacter{00A8}{\"{ }} + \DeclareUnicodeCharacter{00A9}{\copyright} + \DeclareUnicodeCharacter{00AA}{\ordf} + \DeclareUnicodeCharacter{00AB}{\guillemetleft} + \DeclareUnicodeCharacter{00AD}{\-} + \DeclareUnicodeCharacter{00AE}{\registeredsymbol} + \DeclareUnicodeCharacter{00AF}{\={ }} + + \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} + \DeclareUnicodeCharacter{00B4}{\'{ }} + \DeclareUnicodeCharacter{00B8}{\cedilla{ }} + \DeclareUnicodeCharacter{00BA}{\ordm} + \DeclareUnicodeCharacter{00BB}{\guillemetright} + \DeclareUnicodeCharacter{00BF}{\questiondown} + + \DeclareUnicodeCharacter{00C0}{\`A} + \DeclareUnicodeCharacter{00C1}{\'A} + \DeclareUnicodeCharacter{00C2}{\^A} + \DeclareUnicodeCharacter{00C3}{\~A} + \DeclareUnicodeCharacter{00C4}{\"A} + \DeclareUnicodeCharacter{00C5}{\AA} + \DeclareUnicodeCharacter{00C6}{\AE} + \DeclareUnicodeCharacter{00C7}{\cedilla{C}} + \DeclareUnicodeCharacter{00C8}{\`E} + \DeclareUnicodeCharacter{00C9}{\'E} + \DeclareUnicodeCharacter{00CA}{\^E} + \DeclareUnicodeCharacter{00CB}{\"E} + \DeclareUnicodeCharacter{00CC}{\`I} + \DeclareUnicodeCharacter{00CD}{\'I} + \DeclareUnicodeCharacter{00CE}{\^I} + \DeclareUnicodeCharacter{00CF}{\"I} + + \DeclareUnicodeCharacter{00D0}{\DH} + \DeclareUnicodeCharacter{00D1}{\~N} + \DeclareUnicodeCharacter{00D2}{\`O} + \DeclareUnicodeCharacter{00D3}{\'O} + \DeclareUnicodeCharacter{00D4}{\^O} + \DeclareUnicodeCharacter{00D5}{\~O} + \DeclareUnicodeCharacter{00D6}{\"O} + \DeclareUnicodeCharacter{00D8}{\O} + \DeclareUnicodeCharacter{00D9}{\`U} + \DeclareUnicodeCharacter{00DA}{\'U} + \DeclareUnicodeCharacter{00DB}{\^U} + \DeclareUnicodeCharacter{00DC}{\"U} + \DeclareUnicodeCharacter{00DD}{\'Y} + \DeclareUnicodeCharacter{00DE}{\TH} + \DeclareUnicodeCharacter{00DF}{\ss} + + \DeclareUnicodeCharacter{00E0}{\`a} + \DeclareUnicodeCharacter{00E1}{\'a} + \DeclareUnicodeCharacter{00E2}{\^a} + \DeclareUnicodeCharacter{00E3}{\~a} + \DeclareUnicodeCharacter{00E4}{\"a} + \DeclareUnicodeCharacter{00E5}{\aa} + \DeclareUnicodeCharacter{00E6}{\ae} + \DeclareUnicodeCharacter{00E7}{\cedilla{c}} + \DeclareUnicodeCharacter{00E8}{\`e} + \DeclareUnicodeCharacter{00E9}{\'e} + \DeclareUnicodeCharacter{00EA}{\^e} + \DeclareUnicodeCharacter{00EB}{\"e} + \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}} + \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}} + \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}} + \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}} + + \DeclareUnicodeCharacter{00F0}{\dh} + \DeclareUnicodeCharacter{00F1}{\~n} + \DeclareUnicodeCharacter{00F2}{\`o} + \DeclareUnicodeCharacter{00F3}{\'o} + \DeclareUnicodeCharacter{00F4}{\^o} + \DeclareUnicodeCharacter{00F5}{\~o} + \DeclareUnicodeCharacter{00F6}{\"o} + \DeclareUnicodeCharacter{00F8}{\o} + \DeclareUnicodeCharacter{00F9}{\`u} + \DeclareUnicodeCharacter{00FA}{\'u} + \DeclareUnicodeCharacter{00FB}{\^u} + \DeclareUnicodeCharacter{00FC}{\"u} + \DeclareUnicodeCharacter{00FD}{\'y} + \DeclareUnicodeCharacter{00FE}{\th} + \DeclareUnicodeCharacter{00FF}{\"y} + + \DeclareUnicodeCharacter{0100}{\=A} + \DeclareUnicodeCharacter{0101}{\=a} + \DeclareUnicodeCharacter{0102}{\u{A}} + \DeclareUnicodeCharacter{0103}{\u{a}} + \DeclareUnicodeCharacter{0104}{\ogonek{A}} + \DeclareUnicodeCharacter{0105}{\ogonek{a}} + \DeclareUnicodeCharacter{0106}{\'C} + \DeclareUnicodeCharacter{0107}{\'c} + \DeclareUnicodeCharacter{0108}{\^C} + \DeclareUnicodeCharacter{0109}{\^c} + \DeclareUnicodeCharacter{0118}{\ogonek{E}} + \DeclareUnicodeCharacter{0119}{\ogonek{e}} + \DeclareUnicodeCharacter{010A}{\dotaccent{C}} + \DeclareUnicodeCharacter{010B}{\dotaccent{c}} + \DeclareUnicodeCharacter{010C}{\v{C}} + \DeclareUnicodeCharacter{010D}{\v{c}} + \DeclareUnicodeCharacter{010E}{\v{D}} + + \DeclareUnicodeCharacter{0112}{\=E} + \DeclareUnicodeCharacter{0113}{\=e} + \DeclareUnicodeCharacter{0114}{\u{E}} + \DeclareUnicodeCharacter{0115}{\u{e}} + \DeclareUnicodeCharacter{0116}{\dotaccent{E}} + \DeclareUnicodeCharacter{0117}{\dotaccent{e}} + \DeclareUnicodeCharacter{011A}{\v{E}} + \DeclareUnicodeCharacter{011B}{\v{e}} + \DeclareUnicodeCharacter{011C}{\^G} + \DeclareUnicodeCharacter{011D}{\^g} + \DeclareUnicodeCharacter{011E}{\u{G}} + \DeclareUnicodeCharacter{011F}{\u{g}} + + \DeclareUnicodeCharacter{0120}{\dotaccent{G}} + \DeclareUnicodeCharacter{0121}{\dotaccent{g}} + \DeclareUnicodeCharacter{0124}{\^H} + \DeclareUnicodeCharacter{0125}{\^h} + \DeclareUnicodeCharacter{0128}{\~I} + \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} + \DeclareUnicodeCharacter{012A}{\=I} + \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} + \DeclareUnicodeCharacter{012C}{\u{I}} + \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} + + \DeclareUnicodeCharacter{0130}{\dotaccent{I}} + \DeclareUnicodeCharacter{0131}{\dotless{i}} + \DeclareUnicodeCharacter{0132}{IJ} + \DeclareUnicodeCharacter{0133}{ij} + \DeclareUnicodeCharacter{0134}{\^J} + \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} + \DeclareUnicodeCharacter{0139}{\'L} + \DeclareUnicodeCharacter{013A}{\'l} + + \DeclareUnicodeCharacter{0141}{\L} + \DeclareUnicodeCharacter{0142}{\l} + \DeclareUnicodeCharacter{0143}{\'N} + \DeclareUnicodeCharacter{0144}{\'n} + \DeclareUnicodeCharacter{0147}{\v{N}} + \DeclareUnicodeCharacter{0148}{\v{n}} + \DeclareUnicodeCharacter{014C}{\=O} + \DeclareUnicodeCharacter{014D}{\=o} + \DeclareUnicodeCharacter{014E}{\u{O}} + \DeclareUnicodeCharacter{014F}{\u{o}} + + \DeclareUnicodeCharacter{0150}{\H{O}} + \DeclareUnicodeCharacter{0151}{\H{o}} + \DeclareUnicodeCharacter{0152}{\OE} + \DeclareUnicodeCharacter{0153}{\oe} + \DeclareUnicodeCharacter{0154}{\'R} + \DeclareUnicodeCharacter{0155}{\'r} + \DeclareUnicodeCharacter{0158}{\v{R}} + \DeclareUnicodeCharacter{0159}{\v{r}} + \DeclareUnicodeCharacter{015A}{\'S} + \DeclareUnicodeCharacter{015B}{\'s} + \DeclareUnicodeCharacter{015C}{\^S} + \DeclareUnicodeCharacter{015D}{\^s} + \DeclareUnicodeCharacter{015E}{\cedilla{S}} + \DeclareUnicodeCharacter{015F}{\cedilla{s}} + + \DeclareUnicodeCharacter{0160}{\v{S}} + \DeclareUnicodeCharacter{0161}{\v{s}} + \DeclareUnicodeCharacter{0162}{\cedilla{t}} + \DeclareUnicodeCharacter{0163}{\cedilla{T}} + \DeclareUnicodeCharacter{0164}{\v{T}} + + \DeclareUnicodeCharacter{0168}{\~U} + \DeclareUnicodeCharacter{0169}{\~u} + \DeclareUnicodeCharacter{016A}{\=U} + \DeclareUnicodeCharacter{016B}{\=u} + \DeclareUnicodeCharacter{016C}{\u{U}} + \DeclareUnicodeCharacter{016D}{\u{u}} + \DeclareUnicodeCharacter{016E}{\ringaccent{U}} + \DeclareUnicodeCharacter{016F}{\ringaccent{u}} + + \DeclareUnicodeCharacter{0170}{\H{U}} + \DeclareUnicodeCharacter{0171}{\H{u}} + \DeclareUnicodeCharacter{0174}{\^W} + \DeclareUnicodeCharacter{0175}{\^w} + \DeclareUnicodeCharacter{0176}{\^Y} + \DeclareUnicodeCharacter{0177}{\^y} + \DeclareUnicodeCharacter{0178}{\"Y} + \DeclareUnicodeCharacter{0179}{\'Z} + \DeclareUnicodeCharacter{017A}{\'z} + \DeclareUnicodeCharacter{017B}{\dotaccent{Z}} + \DeclareUnicodeCharacter{017C}{\dotaccent{z}} + \DeclareUnicodeCharacter{017D}{\v{Z}} + \DeclareUnicodeCharacter{017E}{\v{z}} + + \DeclareUnicodeCharacter{01C4}{D\v{Z}} + \DeclareUnicodeCharacter{01C5}{D\v{z}} + \DeclareUnicodeCharacter{01C6}{d\v{z}} + \DeclareUnicodeCharacter{01C7}{LJ} + \DeclareUnicodeCharacter{01C8}{Lj} + \DeclareUnicodeCharacter{01C9}{lj} + \DeclareUnicodeCharacter{01CA}{NJ} + \DeclareUnicodeCharacter{01CB}{Nj} + \DeclareUnicodeCharacter{01CC}{nj} + \DeclareUnicodeCharacter{01CD}{\v{A}} + \DeclareUnicodeCharacter{01CE}{\v{a}} + \DeclareUnicodeCharacter{01CF}{\v{I}} + + \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}} + \DeclareUnicodeCharacter{01D1}{\v{O}} + \DeclareUnicodeCharacter{01D2}{\v{o}} + \DeclareUnicodeCharacter{01D3}{\v{U}} + \DeclareUnicodeCharacter{01D4}{\v{u}} + + \DeclareUnicodeCharacter{01E2}{\={\AE}} + \DeclareUnicodeCharacter{01E3}{\={\ae}} + \DeclareUnicodeCharacter{01E6}{\v{G}} + \DeclareUnicodeCharacter{01E7}{\v{g}} + \DeclareUnicodeCharacter{01E8}{\v{K}} + \DeclareUnicodeCharacter{01E9}{\v{k}} + + \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}} + \DeclareUnicodeCharacter{01F1}{DZ} + \DeclareUnicodeCharacter{01F2}{Dz} + \DeclareUnicodeCharacter{01F3}{dz} + \DeclareUnicodeCharacter{01F4}{\'G} + \DeclareUnicodeCharacter{01F5}{\'g} + \DeclareUnicodeCharacter{01F8}{\`N} + \DeclareUnicodeCharacter{01F9}{\`n} + \DeclareUnicodeCharacter{01FC}{\'{\AE}} + \DeclareUnicodeCharacter{01FD}{\'{\ae}} + \DeclareUnicodeCharacter{01FE}{\'{\O}} + \DeclareUnicodeCharacter{01FF}{\'{\o}} + + \DeclareUnicodeCharacter{021E}{\v{H}} + \DeclareUnicodeCharacter{021F}{\v{h}} + + \DeclareUnicodeCharacter{0226}{\dotaccent{A}} + \DeclareUnicodeCharacter{0227}{\dotaccent{a}} + \DeclareUnicodeCharacter{0228}{\cedilla{E}} + \DeclareUnicodeCharacter{0229}{\cedilla{e}} + \DeclareUnicodeCharacter{022E}{\dotaccent{O}} + \DeclareUnicodeCharacter{022F}{\dotaccent{o}} + + \DeclareUnicodeCharacter{0232}{\=Y} + \DeclareUnicodeCharacter{0233}{\=y} + \DeclareUnicodeCharacter{0237}{\dotless{j}} + + \DeclareUnicodeCharacter{02DB}{\ogonek{ }} + + \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} + \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} + \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} + \DeclareUnicodeCharacter{1E05}{\udotaccent{b}} + \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}} + \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}} + \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}} + \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}} + \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}} + \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}} + \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}} + \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}} + + \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}} + \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}} + + \DeclareUnicodeCharacter{1E20}{\=G} + \DeclareUnicodeCharacter{1E21}{\=g} + \DeclareUnicodeCharacter{1E22}{\dotaccent{H}} + \DeclareUnicodeCharacter{1E23}{\dotaccent{h}} + \DeclareUnicodeCharacter{1E24}{\udotaccent{H}} + \DeclareUnicodeCharacter{1E25}{\udotaccent{h}} + \DeclareUnicodeCharacter{1E26}{\"H} + \DeclareUnicodeCharacter{1E27}{\"h} + + \DeclareUnicodeCharacter{1E30}{\'K} + \DeclareUnicodeCharacter{1E31}{\'k} + \DeclareUnicodeCharacter{1E32}{\udotaccent{K}} + \DeclareUnicodeCharacter{1E33}{\udotaccent{k}} + \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}} + \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}} + \DeclareUnicodeCharacter{1E36}{\udotaccent{L}} + \DeclareUnicodeCharacter{1E37}{\udotaccent{l}} + \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}} + \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}} + \DeclareUnicodeCharacter{1E3E}{\'M} + \DeclareUnicodeCharacter{1E3F}{\'m} + + \DeclareUnicodeCharacter{1E40}{\dotaccent{M}} + \DeclareUnicodeCharacter{1E41}{\dotaccent{m}} + \DeclareUnicodeCharacter{1E42}{\udotaccent{M}} + \DeclareUnicodeCharacter{1E43}{\udotaccent{m}} + \DeclareUnicodeCharacter{1E44}{\dotaccent{N}} + \DeclareUnicodeCharacter{1E45}{\dotaccent{n}} + \DeclareUnicodeCharacter{1E46}{\udotaccent{N}} + \DeclareUnicodeCharacter{1E47}{\udotaccent{n}} + \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}} + \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}} + + \DeclareUnicodeCharacter{1E54}{\'P} + \DeclareUnicodeCharacter{1E55}{\'p} + \DeclareUnicodeCharacter{1E56}{\dotaccent{P}} + \DeclareUnicodeCharacter{1E57}{\dotaccent{p}} + \DeclareUnicodeCharacter{1E58}{\dotaccent{R}} + \DeclareUnicodeCharacter{1E59}{\dotaccent{r}} + \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}} + \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}} + \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}} + \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}} + + \DeclareUnicodeCharacter{1E60}{\dotaccent{S}} + \DeclareUnicodeCharacter{1E61}{\dotaccent{s}} + \DeclareUnicodeCharacter{1E62}{\udotaccent{S}} + \DeclareUnicodeCharacter{1E63}{\udotaccent{s}} + \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}} + \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}} + \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}} + \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}} + \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}} + \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}} + + \DeclareUnicodeCharacter{1E7C}{\~V} + \DeclareUnicodeCharacter{1E7D}{\~v} + \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}} + \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}} + + \DeclareUnicodeCharacter{1E80}{\`W} + \DeclareUnicodeCharacter{1E81}{\`w} + \DeclareUnicodeCharacter{1E82}{\'W} + \DeclareUnicodeCharacter{1E83}{\'w} + \DeclareUnicodeCharacter{1E84}{\"W} + \DeclareUnicodeCharacter{1E85}{\"w} + \DeclareUnicodeCharacter{1E86}{\dotaccent{W}} + \DeclareUnicodeCharacter{1E87}{\dotaccent{w}} + \DeclareUnicodeCharacter{1E88}{\udotaccent{W}} + \DeclareUnicodeCharacter{1E89}{\udotaccent{w}} + \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}} + \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}} + \DeclareUnicodeCharacter{1E8C}{\"X} + \DeclareUnicodeCharacter{1E8D}{\"x} + \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}} + \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}} + + \DeclareUnicodeCharacter{1E90}{\^Z} + \DeclareUnicodeCharacter{1E91}{\^z} + \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}} + \DeclareUnicodeCharacter{1E93}{\udotaccent{z}} + \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}} + \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}} + \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}} + \DeclareUnicodeCharacter{1E97}{\"t} + \DeclareUnicodeCharacter{1E98}{\ringaccent{w}} + \DeclareUnicodeCharacter{1E99}{\ringaccent{y}} + + \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}} + \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}} + + \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}} + \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}} + \DeclareUnicodeCharacter{1EBC}{\~E} + \DeclareUnicodeCharacter{1EBD}{\~e} + + \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}} + \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}} + \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}} + \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}} + + \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}} + \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}} + + \DeclareUnicodeCharacter{1EF2}{\`Y} + \DeclareUnicodeCharacter{1EF3}{\`y} + \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}} + + \DeclareUnicodeCharacter{1EF8}{\~Y} + \DeclareUnicodeCharacter{1EF9}{\~y} + + \DeclareUnicodeCharacter{2013}{--} + \DeclareUnicodeCharacter{2014}{---} + \DeclareUnicodeCharacter{2018}{\quoteleft} + \DeclareUnicodeCharacter{2019}{\quoteright} + \DeclareUnicodeCharacter{201A}{\quotesinglbase} + \DeclareUnicodeCharacter{201C}{\quotedblleft} + \DeclareUnicodeCharacter{201D}{\quotedblright} + \DeclareUnicodeCharacter{201E}{\quotedblbase} + \DeclareUnicodeCharacter{2022}{\bullet} + \DeclareUnicodeCharacter{2026}{\dots} + \DeclareUnicodeCharacter{2039}{\guilsinglleft} + \DeclareUnicodeCharacter{203A}{\guilsinglright} + \DeclareUnicodeCharacter{20AC}{\euro} + + \DeclareUnicodeCharacter{2192}{\expansion} + \DeclareUnicodeCharacter{21D2}{\result} + + \DeclareUnicodeCharacter{2212}{\minus} + \DeclareUnicodeCharacter{2217}{\point} + \DeclareUnicodeCharacter{2261}{\equiv} +}% end of \utfeightchardefs + + +% US-ASCII character definitions. +\def\asciichardefs{% nothing need be done + \relax +} + +% Make non-ASCII characters printable again for compatibility with +% existing Texinfo documents that may use them, even without declaring a +% document encoding. +% +\setnonasciicharscatcode \other + + +\message{formatting,} + +\newdimen\defaultparindent \defaultparindent = 15pt + +\chapheadingskip = 15pt plus 4pt minus 2pt +\secheadingskip = 12pt plus 3pt minus 2pt +\subsecheadingskip = 9pt plus 2pt minus 2pt + +% Prevent underfull vbox error messages. +\vbadness = 10000 + +% Don't be very finicky about underfull hboxes, either. +\hbadness = 6666 + +% Following George Bush, get rid of widows and orphans. +\widowpenalty=10000 +\clubpenalty=10000 + +% Use TeX 3.0's \emergencystretch to help line breaking, but if we're +% using an old version of TeX, don't do anything. We want the amount of +% stretch added to depend on the line length, hence the dependence on +% \hsize. We call this whenever the paper size is set. +% +\def\setemergencystretch{% + \ifx\emergencystretch\thisisundefined + % Allow us to assign to \emergencystretch anyway. + \def\emergencystretch{\dimen0}% + \else + \emergencystretch = .15\hsize + \fi +} + +% Parameters in order: 1) textheight; 2) textwidth; +% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; +% 7) physical page height; 8) physical page width. +% +% We also call \setleading{\textleading}, so the caller should define +% \textleading. The caller should also set \parskip. +% +\def\internalpagesizes#1#2#3#4#5#6#7#8{% + \voffset = #3\relax + \topskip = #6\relax + \splittopskip = \topskip + % + \vsize = #1\relax + \advance\vsize by \topskip + \outervsize = \vsize + \advance\outervsize by 2\topandbottommargin + \pageheight = \vsize + % + \hsize = #2\relax + \outerhsize = \hsize + \advance\outerhsize by 0.5in + \pagewidth = \hsize + % + \normaloffset = #4\relax + \bindingoffset = #5\relax + % + \ifpdf + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + % if we don't reset these, they will remain at "1 true in" of + % whatever layout pdftex was dumped with. + \pdfhorigin = 1 true in + \pdfvorigin = 1 true in + \fi + % + \setleading{\textleading} + % + \parindent = \defaultparindent + \setemergencystretch +} + +% @letterpaper (the default). +\def\letterpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % If page is nothing but text, make it come out even. + \internalpagesizes{607.2pt}{6in}% that's 46 lines + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% +}} + +% Use @smallbook to reset parameters for 7x9.25 trim size. +\def\smallbook{{\globaldefs = 1 + \parskip = 2pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.5in}{5in}% + {-.2in}{0in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% + % + \lispnarrowing = 0.3in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .5cm +}} + +% Use @smallerbook to reset parameters for 6x9 trim size. +% (Just testing, parameters still in flux.) +\def\smallerbook{{\globaldefs = 1 + \parskip = 1.5pt plus 1pt + \textleading = 12pt + % + \internalpagesizes{7.4in}{4.8in}% + {-.2in}{-.4in}% + {0pt}{14pt}% + {9in}{6in}% + % + \lispnarrowing = 0.25in + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = .4cm +}} + +% Use @afourpaper to print on European A4 paper. +\def\afourpaper{{\globaldefs = 1 + \parskip = 3pt plus 2pt minus 1pt + \textleading = 13.2pt + % + % Double-side printing via postscript on Laserjet 4050 + % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. + % To change the settings for a different printer or situation, adjust + % \normaloffset until the front-side and back-side texts align. Then + % do the same for \bindingoffset. You can set these for testing in + % your texinfo source file like this: + % @tex + % \global\normaloffset = -6mm + % \global\bindingoffset = 10mm + % @end tex + \internalpagesizes{673.2pt}{160mm}% that's 51 lines + {\voffset}{\hoffset}% + {\bindingoffset}{44pt}% + {297mm}{210mm}% + % + \tolerance = 700 + \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = 5mm +}} + +% Use @afivepaper to print on European A5 paper. +% From romildo@urano.iceb.ufop.br, 2 July 2000. +% He also recommends making @example and @lisp be small. +\def\afivepaper{{\globaldefs = 1 + \parskip = 2pt plus 1pt minus 0.1pt + \textleading = 12.5pt + % + \internalpagesizes{160mm}{120mm}% + {\voffset}{\hoffset}% + {\bindingoffset}{8pt}% + {210mm}{148mm}% + % + \lispnarrowing = 0.2in + \tolerance = 800 + \hfuzz = 1.2pt + \contentsrightmargin = 0pt + \defbodyindent = 2mm + \tableindent = 12mm +}} + +% A specific text layout, 24x15cm overall, intended for A4 paper. +\def\afourlatex{{\globaldefs = 1 + \afourpaper + \internalpagesizes{237mm}{150mm}% + {\voffset}{4.6mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + % + % Must explicitly reset to 0 because we call \afourpaper. + \globaldefs = 0 +}} + +% Use @afourwide to print on A4 paper in landscape format. +\def\afourwide{{\globaldefs = 1 + \afourpaper + \internalpagesizes{241mm}{165mm}% + {\voffset}{-2.95mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + \globaldefs = 0 +}} + +% @pagesizes TEXTHEIGHT[,TEXTWIDTH] +% Perhaps we should allow setting the margins, \topskip, \parskip, +% and/or leading, also. Or perhaps we should compute them somehow. +% +\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} +\def\pagesizesyyy#1,#2,#3\finish{{% + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi + \globaldefs = 1 + % + \parskip = 3pt plus 2pt minus 1pt + \setleading{\textleading}% + % + \dimen0 = #1\relax + \advance\dimen0 by \voffset + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% +}} + +% Set default to letter. +% +\letterpaper + + +\message{and turning on texinfo input format.} + +\def^^L{\par} % remove \outer, so ^L can appear in an @comment + +% DEL is a comment character, in case @c does not suffice. +\catcode`\^^? = 14 + +% Define macros to output various characters with catcode for normal text. +\catcode`\"=\other \def\normaldoublequote{"} +\catcode`\$=\other \def\normaldollar{$}%$ font-lock fix +\catcode`\+=\other \def\normalplus{+} +\catcode`\<=\other \def\normalless{<} +\catcode`\>=\other \def\normalgreater{>} +\catcode`\^=\other \def\normalcaret{^} +\catcode`\_=\other \def\normalunderscore{_} +\catcode`\|=\other \def\normalverticalbar{|} +\catcode`\~=\other \def\normaltilde{~} + +% This macro is used to make a character print one way in \tt +% (where it can probably be output as-is), and another way in other fonts, +% where something hairier probably needs to be done. +% +% #1 is what to print if we are indeed using \tt; #2 is what to print +% otherwise. Since all the Computer Modern typewriter fonts have zero +% interword stretch (and shrink), and it is reasonable to expect all +% typewriter fonts to have this, we can check that font parameter. +% +\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} + +% Same as above, but check for italic font. Actually this also catches +% non-italic slanted fonts since it is impossible to distinguish them from +% italic fonts. But since this is only used by $ and it uses \sl anyway +% this is not a problem. +\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} + +% Turn off all special characters except @ +% (and those which the user can use as if they were ordinary). +% Most of these we simply print from the \tt font, but for some, we can +% use math or other variants that look better in normal text. + +\catcode`\"=\active +\def\activedoublequote{{\tt\char34}} +\let"=\activedoublequote +\catcode`\~=\active +\def~{{\tt\char126}} +\chardef\hat=`\^ +\catcode`\^=\active +\def^{{\tt \hat}} + +\catcode`\_=\active +\def_{\ifusingtt\normalunderscore\_} +\let\realunder=_ +% Subroutine for the previous macro. +\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } + +\catcode`\|=\active +\def|{{\tt\char124}} +\chardef \less=`\< +\catcode`\<=\active +\def<{{\tt \less}} +\chardef \gtr=`\> +\catcode`\>=\active +\def>{{\tt \gtr}} +\catcode`\+=\active +\def+{{\tt \char 43}} +\catcode`\$=\active +\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix + +% If a .fmt file is being used, characters that might appear in a file +% name cannot be active until we have parsed the command line. +% So turn them off again, and have \everyjob (or @setfilename) turn them on. +% \otherifyactive is called near the end of this file. +\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} + +% Used sometimes to turn off (effectively) the active characters even after +% parsing them. +\def\turnoffactive{% + \normalturnoffactive + \otherbackslash +} + +\catcode`\@=0 + +% \backslashcurfont outputs one backslash character in current font, +% as in \char`\\. +\global\chardef\backslashcurfont=`\\ +\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work + +% \realbackslash is an actual character `\' with catcode other, and +% \doublebackslash is two of them (for the pdf outlines). +{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} + +% In texinfo, backslash is an active character; it prints the backslash +% in fixed width font. +\catcode`\\=\active % @ for escape char from now on. + +% The story here is that in math mode, the \char of \backslashcurfont +% ends up printing the roman \ from the math symbol font (because \char +% in math mode uses the \mathcode, and plain.tex sets +% \mathcode`\\="026E). It seems better for @backslashchar{} to always +% print a typewriter backslash, hence we use an explicit \mathchar, +% which is the decimal equivalent of "715c (class 7, e.g., use \fam; +% ignored family value; char position "5C). We can't use " for the +% usual hex value because it has already been made active. +@def@normalbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}} +@let@backslashchar = @normalbackslash % @backslashchar{} is for user documents. + +% On startup, @fixbackslash assigns: +% @let \ = @normalbackslash +% \rawbackslash defines an active \ to do \backslashcurfont. +% \otherbackslash defines an active \ to be a literal `\' character with +% catcode other. We switch back and forth between these. +@gdef@rawbackslash{@let\=@backslashcurfont} +@gdef@otherbackslash{@let\=@realbackslash} + +% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of +% the literal character `\'. Also revert - to its normal character, in +% case the active - from code has slipped in. +% +{@catcode`- = @active + @gdef@normalturnoffactive{% + @let-=@normaldash + @let"=@normaldoublequote + @let$=@normaldollar %$ font-lock fix + @let+=@normalplus + @let<=@normalless + @let>=@normalgreater + @let\=@normalbackslash + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let~=@normaltilde + @markupsetuplqdefault + @markupsetuprqdefault + @unsepspaces + } +} + +% Make _ and + \other characters, temporarily. +% This is canceled by @fixbackslash. +@otherifyactive + +% If a .fmt file is being used, we don't want the `\input texinfo' to show up. +% That is what \eatinput is for; after that, the `\' should revert to printing +% a backslash. +% +@gdef@eatinput input texinfo{@fixbackslash} +@global@let\ = @eatinput + +% On the other hand, perhaps the file did not have a `\input texinfo'. Then +% the first `\' in the file would cause an error. This macro tries to fix +% that, assuming it is called before the first `\' could plausibly occur. +% Also turn back on active characters that might appear in the input +% file name, in case not using a pre-dumped format. +% +@gdef@fixbackslash{% + @ifx\@eatinput @let\ = @normalbackslash @fi + @catcode`+=@active + @catcode`@_=@active +} + +% Say @foo, not \foo, in error messages. +@escapechar = `@@ + +% These (along with & and #) are made active for url-breaking, so need +% active definitions as the normal characters. +@def@normaldot{.} +@def@normalquest{?} +@def@normalslash{/} + +% These look ok in all fonts, so just make them not special. +% @hashchar{} gets its own user-level command, because of #line. +@catcode`@& = @other @def@normalamp{&} +@catcode`@# = @other @def@normalhash{#} +@catcode`@% = @other @def@normalpercent{%} + +@let @hashchar = @normalhash + +@c Finally, make ` and ' active, so that txicodequoteundirected and +@c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}. If we +@c don't make ` and ' active, @code will not get them as active chars. +@c Do this last of all since we use ` in the previous @catcode assignments. +@catcode`@'=@active +@catcode`@`=@active +@markupsetuplqdefault +@markupsetuprqdefault + +@c Local variables: +@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c page-delimiter: "^\\\\message" +@c time-stamp-start: "def\\\\texinfoversion{" +@c time-stamp-format: "%:y-%02m-%02d.%02H" +@c time-stamp-end: "}" +@c End: + +@c vim:sw=2: + +@ignore + arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 +@end ignore diff --git a/gmp-6.3.0/doc/version.texi b/gmp-6.3.0/doc/version.texi new file mode 100644 index 0000000..6c23458 --- /dev/null +++ b/gmp-6.3.0/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 29 July 2023 +@set UPDATED-MONTH July 2023 +@set EDITION 6.3.0 +@set VERSION 6.3.0 -- cgit v1.2.3