@comment -*-texinfo-*-
@comment $Id: types.doc,v 1.28 1998-05-08 07:49:26 wichmann Exp $
@comment this file contains the type definitions

@c The following directives are necessary for proper compilation
@c with emacs (C-c C-e C-b).
@c @setfilename types.info
@c @node Top, Data types
@c @menu
@c * Data types::
@c @end menu
@c @node Data types, , Top, Top
@c @chapter Data types

@menu
* def::
* ideal::
* int::
* intmat::
* intvec::
* link::
* list::
* map::
* matrix::
* module::
* number::
* poly::
* proc::
* qring::
* resolution::
* ring::
* string::
* vector::
@end menu

@cindex expression list
An expression list is any comma separated list of expressions.
@*@strong{Example:}
@example
@c example
  ring r;
  poly f=x2-y3;
  int i=37;
  string s1="abc";
  string s2="def";
  string s=s1,s2; // typecast from expression list to string
  s;
  s1,s2;
  f,i,s;
@c example
@end example

@c ---------------------------------------
@node def, ideal, , Data types
@section def
@cindex def
@cindex untyped definitions

@c {{{ section def }}}
@c ------------------------------
@menu
* def declarations::
@end menu

Objects may also be defined without a type: they get their
type from the first assignment to them.
E.g. @code{ideal i=x,y,z; def j=i^2;} defines the ideal @code{i^2}
with the name @code{j}.
@*Note: Unlike other assignments a ring as an untyped object
is not a copy but another reference to the same ring.
@example
  ring r;
  def s=basering;
  setring s;
@end example
defines a ring @code{s} which is just another reference (or name)
for the @code{basering}. This is useful if the basering
is not local to the procedure (so it cannot be accessed by its name)
but you need a name for it (e.g. for a use with @code{setring} or @code{map}).
@code{setring r;} does not work in this case, because
@code{r} may not be local to the procedure.

@c ------------------------------
@node def declarations, , def, def
@subsection def declarations
@cindex def declarations

@c {{{ subsection def declarations }}}
@table @code
@item @strong{Syntax:}
@code{def} name @code{=} expression @code{;}
@item @strong{Purpose:}
defines an object of the same type as the right-hand side.
@item @strong{Default:}
none
@item @strong{Note:}
This is useful if the right-hand side may be of
variable type as a consequence of a computation (e.g. ideal or module or
matrix). It is also used in procedures to give the basering a name which
is local to the procedure.
@item @strong{Example:}
@example
@c example
  def i=2;
  typeof(i);
@c example
@end example
@end table
@c ref
See @ref{def}; @ref{typeof}.
@c ref
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node ideal, int, def, Data types
@section ideal
@cindex ideal

@c {{{ section ideal }}}
@menu
* ideal declarations::
* ideal expressions::
* ideal operations::
* ideal related functions::
@end menu

Ideals are represented as lists of polynomials which generate the ideal.
Like polynomials they
can only be defined or accessed with respect to a base ring.
@example
  ring R;
  poly f=x2+y3;
  ideal i=z2,f;// the ideal generated by z^2,x^2+y^3 in R
@end example

@c ---------------------------------------
@node ideal declarations, ideal expressions, ideal, ideal
@subsection ideal declarations
@cindex ideal declarations

@c {{{ subsection ideal declarations }}}
@table @code
@item @strong{Syntax:}
@code{ideal} name @code{=} list_of_poly_expressions @code{;}
@*@code{ideal} name @code{=} ideal_expression @code{;}
@item @strong{Purpose:}
defines an ideal.
@item @strong{Default:}
0
@item @strong{Example:}
@example
@c example
  ring r=0,(x,y,z),dp;
  poly s1 = x2;
  poly s2 = y3;
  poly s3 = z;
  ideal i =  s1, s2-s1, s2*s3, s3^4;
  i;
  ideal j = i^2;
  // generators i[k]*i[l], 1<=k<=l<=size(i);
  ideal IJ = i*j;
  // generators i[k]*j[l], 1<=k<=size(i), 1<=l<=size(j)
  size(j), size(IJ);
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node ideal expressions, ideal operations, ideal declarations, ideal
@subsection ideal expressions
@cindex ideal expressions

@c {{{ subsection ideal expressions }}}
An ideal expression is:
@enumerate
@item
an expression list of poly expressions
@item
an identifier of type ideal
@item
a function returning ideal
@item
ideal expressions combined by arithmetic operations @code{+,*}
@item
a power of an ideal expression (operator @code{^} or @code{**})
@*Note that the computation of the product i*i involves
all products of generators of i while i^2 involves only the different ones
and is therefore faster
@item
a typecast to ideal.
@end enumerate
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node ideal operations, ideal related functions, ideal expressions, ideal
@subsection ideal operations
@cindex ideal operations

@c {{{ subsection ideal oparations }}}
@table @asis
@item @code{+}
addition (concatenation of the generator and simplification)
@item @code{*}
multiplication (with ideal, poly, vector, module)
@item @code{^}
power, exponentiation (by an integer)
@end table
Brackets may be used to access elements of ideals:
@emph{ideal expressions} @code{[} @emph{position} @code{]} is a generator of the ideal.
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}

@c ------------------------------
@node ideal related functions, ,ideal operations, ideal
@subsection ideal related functions
@cindex ideal related functions

@c {{{ subsection ideal related functions }}}
@table @asis
@item @code{char_series}
ireducible characteristic series (see @ref{char_series})
@item @code{coeffs}
matrix of coefficients (see @ref{coeffs})
@item @code{contract}
contraction by an ideal (see @ref{contract})
@item @code{diff}
partial derivative (see @ref{diff})
@item @code{degree}
multiplicity, dimension and codimension of the ideal of leading terms (see @ref{degree})
@item @code{dim}
Krull dimension of base ring modulo the ideal of leading terms (see @ref{dim})
@item @code{eliminate}
elimination of variables (see @ref{eliminate})
@item @code{facstd}
factorizing Groebner basis algorithm (see @ref{facstd})
@item @code{fglm}
compute the Groebner basis from a GB w.r.t. a different ordering (see @ref{fglm})
@item @code{finduni}
find univariate polynomials in a zero dimensional ideal (see @ref{finduni})
@item @code{homog}
homogenization with respect to a variable (see @ref{homog})
@item @code{hilb}
Hilbert function of a standardbasis (see @ref{hilb})
@item @code{indepSet}
a maximal set of independent variables of an ideal (see @ref{indepSet})
@item @code{interred}
interreduction of an ideal (see @ref{interred})
@item @code{intersect}
ideal intersection (see @ref{intersect})
@item @code{jacob}
ideal of all partial derivatives resp. jacobian matrix (see @ref{jacob})
@item @code{jet}
k-jet: Taylor series up to a given order (see @ref{jet})
@item @code{kbase}
vector space basis of basering modulo standardbasis (see @ref{kbase})
@item @code{koszul}
Koszul matrix (see @ref{koszul})
@item @code{lead}
leading terms of a set of generators (see @ref{lead})
@item @code{lift}
lift-matrix (see @ref{lift})
@item @code{liftstd}
standardbasis and transformation matrix computation (see @ref{liftstd})
@item @code{maxideal}
power of the maximal ideal at 0 (see @ref{maxideal})
@item @code{minbase}
minimal generating set of a homogeneous ideal/module or an ideal/module in a local ring
(see @ref{minbase})
@item @code{minor}
set of minors of a matrix (see @ref{minor})
@item @code{modulo}
represents (h1+h2)/h1=h2/(h1 intersect h2) (see @ref{modulo})
@item @code{mres}
minimal free resolution of an ideal/module, also minimizing the given ideal/module
(see @ref{mres})
@item @code{mstd}
standard basis and minimal generating set of an ideal (see @ref{mstd})
@item @code{mult}
multiplicity of an ideal resp. module (see @ref{mult})
@item @code{ncols}
number of columns (see @ref{ncols})
@item @code{preimage}
preimage under a ring map (see @ref{preimage})
@item @code{qhweight}
quasihomogeneous weights of an ideal (see @ref{qhweight})
@item @code{quotient}
ideal quotient (see @ref{quotient})
@item @code{reduce}
normalform with respect to a standardbasis (see @ref{reduce})
@item @code{res}
minimal free resolution of an ideal/module but not changing the given ideal/module
(see @ref{res})
@item @code{simplify}
simplify a set of polynomials (see @ref{simplify})
@item @code{size}
number of non-zero generators (see @ref{size})
@item @code{sortvec}
permutation for sorting ideals/modules (see @ref{sortvec})
@item @code{sres}
free resolution of a standard basis (see @ref{sres})
@item @code{std}
standardbasis computation (see @ref{std}, @ref{liftstd})
@item @code{subst}
substitute a ring variable (see @ref{subst})
@item @code{syz}
computation of the first syzygy module (see @ref{syz})
@item @code{vdim}
vector space dimension of basering modulo ideal (see @ref{vdim})
@item @code{weight}
optimal weights (see @ref{weight})
@end table
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}

@c {{{endfold}}}

@c ---------------------------------------
@node int, intmat, ideal, Data types
@section int
@cindex int

@c {{{ section int }}}
@menu
* int declarations::
* int expressions::
* int operations::
* boolean expressions::
* boolean operations::
* int related functions::
@end menu

Variables of type int represent the compiler integers and are, therefore,
limited  in their range (i.e. the range is between
-2147483647 and 2147483647 for 32-bit mchines). They are used
to count things (dimension, rank, etc., see @ref{dim}),
in loops (see @ref{for}) and
to represent boolean values
(FALSE is represented by 0, every other value means TRUE).

@c ---------------------------------------
@node int declarations, int expressions, int, int
@subsection int declarations
@cindex int declarations

@c {{{ subsection int declarations }}}
@table @code
@item @strong{Syntax:}
@code{int} name @code{=} int_expression @code{;}
@item @strong{Purpose:}
defines an integer variable.
@item @strong{Default:}
0
@item @strong{Example:}
@example
@c example
  int i = 42;
  int j = i + 3; j;
  i = i * 3 - j; i;
  int k;   // assigning the default value 0 to k
  k;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node int expressions, int operations, int declarations, int
@subsection int expressions
@cindex int expressions

@c {{{ subsection int expression }}}
Integers consist of a sequence of digits, possibly preceded by a sign.
A space is considered as a separator, so it is not allowed between digits.
A sequence of digits outside the allowed range will be converted to the type
poly if possible.
@example
@c example
  int j=1;
  ring r;
  int i=dim(std(ideal(x,y)));// dimension of factor ring defined by (x,y)
                 // (i.e. R/(x,y)) if it is given by a standard basis
  int compare = i<j;
  compare;      // 0 (FALSE) if i >= j, 1 (TRUE) if i<j
@c example
@end example
Integers may be converted to polynomials by an assignment,
e.g.
@example
  poly g=j;
  // define the constant polynomial g equal to the image of
  // the integer j in the actual coefficient field
@end example

An int expression is:
@enumerate
@item
a sequence of digits (if the number represented by this sequence is too
large to fit into the range of integers it is automatically
converted to the type number, if a basering is defined)
@item
an identifier of type int
@item
an element of an intvec or an intmat
@item
a function returning int
@item
a typecast to int
@item
int expressions combined by arithmetic operations
@code{+},@code{-},@code{*},@code{/},@code{%} or @code{^}.
@end enumerate
Variables of type int represent the compiler integers  and are, therefore,
limited  in their range. If this range is too small the expression
must be converted to the type number over a ring with characteristic 0.

@strong{Example:}
@example
@c example
  ring r=0,x,dp;
  // using the type cast number for a greater allowed range
  number(11)*13*17*100*200*2000*503*1111*222222;
  // Note: 11*13*17*100*200*2000*503*1111*222222
  // would return a machine integer:
  11*13*17*100*200*2000*503*1111*222222;
  int i;
  i+2;
  intvec v=i..i+3;
  v;
@c example
@end example
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node int operations, boolean expressions, int expressions, int
@subsection int operations
@cindex int operations
@cindex mod
@cindex div

@c {{{ subsection int operations }}}
@table @asis
@item @code{++}
will change its operand to its successor, is itself no int expression
@item @code{--}
will change its operand to its predecessor, is itself no int expression
@item @code{+}
addition
@item @code{-}
negation or subtraction
@item @code{*}
multiplication
@item @code{div}
division in the integers (omitting the remainder)
@item @code{%}, @code{mod}
modulo (the remainder of the division)
@item @code{^,**}
power, exponentiation
@item @code{<}, @code{>}, @code{<=}, @code{>=}, @code{==}, @code{<>}
comparison
@end table

@strong{Example:}
@example
@c example
  int i=1;
  i++; i ; i--; i; // ++ and -- will not return a value as in C
  i+2, 2-i, 5^2, 5 div 2, 8%3, 1<2, 2<=2;
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node boolean expressions, boolean operations, int operations, int
@subsection boolean expressions
@cindex boolean expressions
@cindex ==
@cindex !=
@cindex <>
@cindex <=
@cindex >=
@cindex and
@cindex &&
@cindex or
@cindex ||
@cindex not

@c {{{ subsection boolean expressions }}}
A boolean expression is really an int expression used in a logical context:
@enumerate
@item
an int expression (<> 0 evaluates to @emph{TRUE}, 0 evaluates to @emph{FALSE})
@item
an integer comparison:
@example
  i == j
  i != j    //or     i <> j
  i <= j
  i >= j
  i > j
  i < j
@end example
@item
a number comparison:
@example
  m == n
  m != n    //or     m <> n
  m < n
  m > n
  m <= n
  m >= n
@end example
For numbers from Z/p or from field extensions not all operations are useful:
@* - 0 ist always the smallest element,
@* - in Z/p the representatives in the range -p/2..p/2 are used for comparisons
@* - in field extensions the last two operations
(@code{>=,<=}) yield always TRUE (1) and
the @code{<} and @code{>} are equivalent to @code{!=}.
@item
a polynomial comparison:
@example
  f == g
  f != g    //or     f <> g
  f <= g    //comparing the leading term w.r.t. the monomial order
  f >= g
@end example
@item
an intvec or intmat comparison:
@example
  v == w
  v != w    //or     v <> w
@end example
@item
a string comparison:
@example
  f == g
  f != g    //or     f <> g
  f <= g    // comparing lexicographically
            // w.r.t. the order specified by ASCII
  f >= g
  f >  g
  f <  g
@end example
@item
boolean expressions combined by boolean operations:
@code{and}, @code{or}, @code{not}.
@*@code{and} may also be written as @code{&&}, @code{or} as @code{||},
@code{not} as @code{!}
(see @ref{Evaluation of logical expressions}).

@strong{Remark:} All arguments of a logical expressions are first
evaluated and then the value of the logical expression is
determined. For example, the logical expressions @code{(1 || a)} is
evaluated by first evaluating @code{a}, even though the value of
@code{a} has no influence on the value of @code{(1 || a)}. Note that
this is different from the left-to-right evaluation of logical
expressions (as found in most programming languages like C) which, for
example, determine the @code{(1 || a)} without evaluating @code{a}.
@end enumerate
@c {{{endfold}}}

@c ------------------------------
@node boolean operations, int related functions, boolean expressions, int
@subsection boolean operations
@cindex boolean operations

@c ------------------------------
@node int related functions,  , boolean operations, int
@subsection int related functions
@cindex int related functions

@c {{{ section int related functions }}}
@table @asis
@item @code{char}
characteristic of the coefficient field of a ring (see @ref{char})
@item @code{deg}
degree of a poly resp. vector (see @ref{deg})
@item @code{det}
determinant (see @ref{det})
@item @code{dim}
Krull dimension of base ring modulo ideal resp. module (see @ref{dim})
@item @code{find}
position of a substring in a string (see @ref{find})
@item @code{gcd}
greatest common divisor (see @ref{gcd})
@item @code{memory}
memory usage (see @ref{memory})
@item @code{mult}
multiplicity of an ideal resp. module (see @ref{mult})
@item @code{ncols}
number of columns (see @ref{ncols})
@item @code{npars}
number of ring parameters (see @ref{npars})
@item @code{nrows}
number of rows of a matrix resp.
the rank of the free module where the vector / module lives
(see @ref{nrows})
@item @code{nvars}
number of ring variables (see @ref{nvars})
@item @code{ord}
degree of the leading term of a poly resp. vector (see @ref{ord})
@item @code{pardeg}
degree of a number considered as a polynomial in the ring parameters (see @ref{pardeg})
@item @code{prime}
the next lower prime (see @ref{prime})
@item @code{random}
a pseudo random integer between the given limits (see @ref{random})
@item @code{regularity}
regularity of a resolution (see @ref{regularity})
@item @code{rvar}
test, if the given expression or string is a ring variable (see @ref{rvar})
@item @code{size}
number of elements in an object (see @ref{size})
@item @code{trace}
trace of an integer matrix (see @ref{trace})
@item @code{vdim}
vector space dimension of base ring modulo ideal resp. of freemodule modulo
module (see @ref{vdim})
@end table
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node intmat, intvec, int, Data types
@section intmat
@cindex intmat

@c {{{ section intmat }}}
@menu
* intmat declarations::
* intmat expressions::
* intmat operations::
* intmat related functions::
@end menu

Integer matrices are matrices with entries of integers.
For the range of integers see @ref{int expressions}.
@example
@c example
  intmat m[2][3]=1,2,3,4,5,6;
  m;
@c example
@end example

@c ------------------------------
@node intmat declarations, intmat expressions, intmat, intmat
@subsection intmat declarations
@cindex intmat declarations

@c {{{ subsection intmat declarations }}}
@table @code
@item @strong{Syntax:}
@code{intmat} name @code{=} intmat_expression @code{;}
@*@code{intmat} name @code{[} rows @code{] [} cols @code{] =} intmat_expression @code{;}
@*@code{intmat} name @code{[} rows @code{] [} cols @code{] =} list_of_int_expressions @code{;}
@item @strong{Purpose:}
defines an intmat variable.
@* Given a list of integers, the matrix is filled up with the first row
from the left to the right, then the second row and so on.
If the int_list contains less than rows*cols elements,
the matrix is filled up with zeros; if it contains more
elements, only the first rows*cols elements are used.
@item @strong{Default:}
0 (1 x 1 matrix)
@item @strong{Example:}
@example
@c example
  intmat im[3][5]=1,3,5,7,8,9,10,11,12,13;
  im;
  im[2,2];
  intmat m[2][3] = im[1..2, 3..5];  // defines a submatrix
  m;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node intmat expressions, intmat operations, intmat declarations, intmat
@subsection intmat expressions
@cindex intmat expressions

@c {{{ subsection intmat expressions }}}
A intmat expression is:
@enumerate
@item
a list of int expressions, intvec expressions and intmat expressions
@item
a function returning intmat (see @ref{intmat related functions})
@item
intmat operations with int: @code{+}, @code{-}, @code{*}, @code{/}, @code{%}
@item
intmat operations: @code{+}, @code{-}, @code{*}
@item
intmat comparison (yielding int): @code{<>}, @code{==}
@end enumerate

@strong{Example:}
@example
@c example
  intmat m[2][3]=1,0,2,4,5,1;
  m+1;             // adds unit intmat to m
  m[2,1];          // entry at 2,1
  intmat m1[3][2]=1,0,2,4,0,1;
  m1*10;           // multiply each entry with 10
  m*m1;
  m+transpose(m1);
  intvec v1=1,2,4;
  intvec v2=5,7,8;
  m=v1,v2;         // overwrite M with v1 and v2
  m;
  trace(m);
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node intmat operations, intmat related functions, intmat expressions, intmat
@subsection intmat operations
@cindex intmat operations

@c ------------------------------
@node intmat related functions, ,intmat operations, intmat
@subsection intmat related functions
@cindex intmat related functions

@c {{{ intmat related functions }}}
@table @asis
@item @code{bareiss}
Bareiss algorithm (see @ref{bareiss})
@item @code{betti}
Betti numbers of a free resolution (see @ref{betti})
@item @code{det}
determinant (see @ref{det})
@item @code{ncols}
number of cols (see @ref{ncols})
@item @code{nrows}
number of rows (see @ref{nrows})
@item @code{random}
create a random intmat (see @ref{random})
@item @code{size}
total number of entries (see @ref{size})
@item @code{transpose}
transpose of an intmat (see @ref{transpose})
@item @code{trace}
trace of an intmat (see @ref{trace})
@end table
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node intvec, link, intmat, Data types
@section intvec
@cindex intvec

@c {{{ section intvec }}}
@menu
* intvec declarations::
* intvec expressions::
* intvec operations::
* intvec related functions::
@end menu

Variables of type intvec are lists of integers.
For the range of integers see @ref{int expressions}.
They can be used for simulating integers sets
(and other sets if the intvec entry is used as an index for other objects).
They are also return values of certain interpreter related functions
(see @ref{Functions}).
@example
@c example
  intvec iv=1,2,5,7;
  iv;
  iv[3];
  iv[7]=1;
  iv;
@c example
@end example

@c ------------------------------
@node intvec declarations, intvec expressions, intvec, intvec
@subsection intvec declarations
@cindex intvec declarations

@c {{{ subsection intvec declarations }}}
@table @code
@item @strong{Syntax:}
@code{intvec} name @code{=} intvec_expression @code{;}
@item @strong{Purpose:}
defines an intvec variable.
@* An intvec consists of an ordered list of integers.
@item @strong{Default:}
0
@item @strong{Example:}
@example
@c example
  intvec iv=1,3,5,7,8;
  iv;
  iv[4];
  iv[3..size (iv)];
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node intvec expressions, intvec operations, intvec declarations, intvec
@subsection intvec expressions
@cindex intvec expressions

@c {{{ intvec expressions }}}
An intvec expression is:
@enumerate
@item
a list of int expressions and of intvec expressions
@item
a range: int expression @code{..} int expression
@item
a function returning intvec (see @ref{intvec related functions})
@item
intvec operations with int: @code{+}, @code{-}, @code{*}, @code{/}, @code{%}
@item
intvec operations: @code{+}, @code{-}
@item
intvec operation with an intmat: @code{*}
@item
intvec comparison (done lexicographically, yielding int):
@code{<>}, @code{==}, @code{<=}, @code{>=}, @code{>}, @code{<}
@end enumerate

@c ref
See @ref{Type conversion and casting}.
@c ref

@strong{Example:}
@example
@c example
  intvec iv=1,3,5,7,8;
  iv=iv,iv;           // concatenation
  iv+1;               // add 1 to each entry
  iv*2;
  iv;
  iv-10;
  iv=iv,0;
  iv;
  iv/2;
  iv+iv;              // componentwise addition
  iv[size(iv)-1];     // last-1 entry
  intvec iw=2,3,4,0;
  iv==iw;             // comparision
  intmat im[2][4];
  im=2,3,4,0,1,0,0,0;
  iv=im*iw;
  iv;
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node intvec operations, intvec related functions, intvec expressions, intvec
@subsection intvec operations
@cindex intvec operations

@c ------------------------------
@node intvec related functions, ,intvec operations, intvec
@subsection intvec related functions
@cindex intvec related functions

@c {{{ intvec related functions }}}
@table @asis
@item @code{hilb}
returns Hilbert series as intvec (see @ref{hilb})
@item @code{indepSet}
indices of a maximal set of independent variables of an ideal (see @ref{indepSet})
@item @code{leadexp}
the exponent vector of the leading monomial (see @ref{leadexp})
@item @code{nrows}
number of rows (see @ref{nrows})
@item @code{qhweight}
returns quasihgomogeneous weights (see @ref{qhweight})
@item @code{size}
length of the intvec (see @ref{size})
@item @code{sortvec}
permutation for sorting ideals/modules (see @ref{sortvec})
@item @code{transpose}
transpose of an intvec, returns an intmat (see @ref{transpose})
@item @code{weight}
returns weights for the weighted ecart method (see @ref{weight})
@end table
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node link, list, intvec, Data types
@section link
@cindex link

@c {{{ section link }}}
@menu
* link declarations::
* link expressions::
* link related functions::
* ASCII links::
* MP links::
* DBM links::
@end menu

Links describe the communication channels of @sc{Singular}, i.e.
something @sc{Singular} can write to and/or read from. Currently,
@sc{Singular} supports four different link types: 
@itemize @bullet
@item ASCII links (see
@ref{ASCII links})

@item MPfile links (see
@ref{MPfile links})

@item MPtcp links (see
@ref{MPtcp links})

@item DBM links (see
@ref{DBM links})
@end itemize

@c ------------------------------
@node link declarations, link expressions, link, link
@subsection link declarations
@cindex link declarations

@c {{{ subsection link declarations }}}
@table @code
@item @strong{Syntax:}
@code{link} name @code{=} string_expression @code{;}
@item @strong{Purpose:}
defines a new communication link.
@item @strong{Default:}
none
@item @strong{Example:}
@example
@c example
  link l=":w example.txt";
  int i=22;
  string s="An int follows:";
  write(l,s,i);
  l;
  close(l);
  read(l);
  read(l);
  close(l);
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node link expressions, link related functions, link declarations, link
@subsection link expressions
@cindex link expressions

@c {{{ subsection link expression }}}
A link expression is:
@enumerate
@item
an identifier of type link
@item
a string describing the link
@end enumerate

A link is described by a string which consists of two parts: a property
string followed by a name string. The property string describes the type
of the link (@code{ASCII}, @code{MPfile}, @code{MPtcp} or @code{DBM})
and the mode of the link (open for read, write or append). The name
string describes the filename of the link, resp. a network connection
for MPtcp links.

For a detailed format description of the link describing string see:
@iftex
@itemize @bullet
@item for ASCII links:
@ref{ASCII links}

@item for MPfile links:
@ref{MPfile links}

@item for MPtcp links:
@ref{MPtcp links}

@item for DBM links:
@ref{DBM links}
@end itemize
@end iftex

@menu
* ASCII links::
* MPfile links::
* MPtcp links::
* DBM links::
@end menu
@c {{{endfold}}}

@c ------------------------------
@node link related functions, ASCII links, link expressions, link
@subsection link related functions
@cindex link related functions

@c {{{ subsection link related functions }}}
@table @asis
@item @code{close}
closes a link (see @ref{close})
@item @code{dump}
generates a dump of all variables and their values (see @ref{dump})
@item @code{getdump}
reads a dump (see @ref{getdump})
@item @code{open}
opens a link (see @ref{open})
@item @code{read}
reads from a link (see @ref{read})
@item @code{status}
gets the status of a link (see @ref{status})
@item @code{write}
writes to a link (see @ref{write})
@item @code{kill}
closes and kills a link (see @ref{kill})
@end table
@c {{{endfold}}}

@c ------------------------------
@node ASCII links, MP links, link related functions, link
@subsection ASCII links
@cindex ASCII links

@c {{{ subsection ASCII links }}}
Via ASCII links data that can be converted to a string can be written
into files for storage or communcation with other programs. The data is
written in plain ASCII format. The output format of polynomials is done
w.r.t. the value of the global variable @code{short} (see @ref{short}). Reading
from an ASCII links returns a string - conversion into other data is up to
the user. This can be done for example using the command @code{execute} 
(see @ref{execute}).

The ASCII link describing string has to be one of the following:

@enumerate
@item @code{"ASCII: "} + filename
@*the mode (read or append) is set by the first @code{read} or
@code{write} command.
@item @code{"ASCII:r "} + filename
@*opens the file for reading.
@item @code{"ASCII:w "} + filename
@*opens the file for overwriting.
@item @code{"ASCII:a "} + filename
@*opens the file for appending.
@end enumerate

There are the following default values:
@itemize @bullet
@item the type @code{ASCII} may be ommitted since ASCII links are the
default links. 

@item if non of @code{r}, @code{w} or @code{a} is specified, the mode of
the link is set by the first @code{read} or @code{write} command on the
link. If the first command is @code{write}, the mode is set to @code{a}
(append mode).

@item if the filename is ommitted, @code{read} reads from stdin and
@code{write} writes to stdout.
@end itemize

Using these default rules, the string @code{":r temp"} describes a link
which is equivalent to the link @code{"ASCII:r temp"}: an ASCII link to
the file @code{temp} which is opened for reading. The string
@code{"temp"} describes an ASCII link to the file @code{temp}, where the
mode is set by the first @code{read} or @code{write} command. See also
the example below.

Note that the filename may contain a path. An ASCII link can be used
either for reading or for writing, but not for both at the same time. A
@code{close} command must be used before a change of i/o
direction. Types without a conversion to @code{string} cannot be
written.

@strong{Example:}
@example
@c example
  ring r=32003,(x,y,z),dp;
  link l=":w example.txt";     // type is ASCII, mode is overwrite
  l;
  status(l, "open", "yes");    // link is not yet opened
  ideal i=x2,y2,z2;
  write (l,1,";",2,";","ideal i=",i,";");
  status(l, "open", "yes");    // now link is open
  status(l, "mode");           // for writing
  write("example.txt","int j=5;");// data is appended to file
  read("example.txt");         // data is returned as string
  close(l);                    // link is closed
  execute read(l);             // read string is executed
  close(l);                    // link is closed
  // dump vars overwriting previous file content:
  dump(":w example.txt");
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node MP links, DBM links, ASCII links, link
@subsection MP links
@cindex MP links

@c {{{ subsection MP links }}}
MP (Multi Protocol) links give the possibility to store and communicate
data in the binary MP format: read and write access is very fast
compared to ASCII links. MP links can be established using files (link
type is @code{MPfile}) or using TCP sockets (link type is
@code{MPtcp}). All data (including such data that can not be converted
to a string) can be written to an MP link. For ring-dependent data, a
ring description is written together with the data. Reading from an MP
link returns an expression (not a string) which was evaluated after the
read operation. If the expression read from an MP link is not from the
same ring as the current ring, then a @code{read} changes the current
ring.  

Currently, MP links are only available on Unix platforms and data is
written without attributes (which is likely to change in future
versions). For a general description of MP, see
@code{http://symbolicnet.mcs.kent.edu:/areas/mp.html}.

@menu
* MPfile links::
* MPtcp links::
@end menu

@node MPfile links, MPtcp links, MP links, MP links
@subsubsection MPfile links
@cindex MPfile links

@c {{{ subsubsection MPfile links }}}
MPfile links provide the possibility to store data in a file using the
binary MP format. Read and write operations are very fast compared to
ASCII links. Therefore, for storing large amounts of data, MPfile links
should be used, instead of ASCII links. Unlike ASCII links, data read
from MPfile links is returned as expressions one at a time, and not as a
string containing the entire content of the file. Furthermore, ring
dependent data is stored together with a ring description. Therefore,
reading ring-dependent data might change the current ring.

The MPfile link describing string has to be one of the following:

@enumerate
@item @code{"MPFile: "} + filename
@*the mode (read or append) is set by the first @code{read} or
@code{write} command. 
@item @code{"MPFile:r "} + filename
@*opens the file for reading.
@item @code{"MPFile:w "} + filename
@*opens the file for overwriting.
@item @code{"MPFile:a "} + filename
@*opens the file for appending.
@end enumerate

There are the following default values:
@itemize @bullet
@item if none of @code{r}, @code{w} or @code{a} is specified, the mode of
the link is set by the first @code{read} or @code{write} command on the
link. If the first command is @code{write}, the mode is set to @code{a}
(append mode).
@end itemize

Note that the filename may contain a path. An MP file link can be used
either for reading or for writing, but not for both at the same time. A
@code{close} command must be used before a change of i/o direction.

@strong{Example:}
@example
@c example
  ring r;
  link l="MPfile:w example.mp"; // type=MPfile, mode=overwrite
  l;
  ideal i=x2,y2,z2;
  write (l,1, i, "hello world");// write three expressions
  status(l, "open", "yes");     // now link is open
  status(l, "mode");            // in write mode
  write(l,4);                   // append one more expression
  close(l);                     // link is closed
  read(l);                      // only first expression is read
  status(l, "open", "yes");     // now link is open
  status(l, "mode");            // for reading
  kill r;
  def i = read(l);              // second expression
  listvar();                    // notice that current ring was set
  def s = read(l);              // third expression
  close(l);                     // link is closed
  dump("MPfile:w example.mp");  // dump everything to example.mp
@c example
@end example
@c {{{endfold}}}

@node MPtcp links,  , MPfile links, MP links
@subsubsection MPtcp links
@cindex MPtcp links

@c {{{ subsubsection MPtcp links }}}
MPtcp links give the possibility to exchange data in the binary MP
format between two processes which may run on the same or different
computers. MPtcp links can be opened in four different modes: 

@table @code
@item listen
@sc{Singular} acts as a server.

@item connect
@sc{Singular} acts as a client.

@item launch
@sc{Singular} acts as a client, launching an application as server.

@item fork
@sc{Singular} acts as a client, forking another @sc{Singular} as
server.
@end table

The MPtcp link describing string has to be
@itemize @bullet
@item listen mode:
@enumerate
@item @code{"MPtcp:listen --MPport "} + portnumber
@end enumerate
@sc{Singular} becomes a server and waits at the port for a
connect call. 
@item connect mode:
@enumerate
@item @code{"MPtcp:connect --MPport "} + portnumber
@item @code{"MPtcp:connect --MPhost" } + hostname + @code{" --MPport "} +
portnumber
@end enumerate
@sc{Singular} becomes a client and connects to a server waiting at
the host and port. 
@item launch mode:
@enumerate
@item @code{"MPtcp:launch"}
@item @code{"MPtcp:launch --MPapplication "} + application
@item @code{"MPtcp:launch --MPhost "} + hostname
@item @code{"MPtcp:launch --MPhost "} + hostname +
@code{" --MPapplication "} + application
@end enumerate
@sc{Singular} becomes a client and starts the application on a
different host which acts as a server.
@item fork mode:
@enumerate
@item @code{"MPtcp:fork"}
@end enumerate
@sc{Singular} becomes a client and forks another @sc{Singular} on the
same host which acts as a server. 
@end itemize

There are the following default values:
@itemize @bullet
@item if none of @code{listen}, @code{connect}, @code{launch} or
@code{fork} is specified, the default mode is set to @code{fork}. 

@item if no application is specified (in mode @code{launch}) the default
application is @code{Singular -b}.

@item if no hostname is specified the localhost is used as default host.
@end itemize

To open a MPtcp link in launch mode, the application to launch must
either be given with an absolute pathname, or must be in a directory
contained in the search path. The launched application acts as a server,
whereas the @sc{Singular} that actually opened the link acts as a
client. @sc{Singular} automatically appends the command line arguments
"@code{--MPmode connect --MPhost} hostname @code{--MPport} portnumber"
to the command line of the server application. Both hostname and
portnumber are substituted by the values from the link
specification. The client "listens" at the given port until the server
application does a connect call. If @sc{Singular} is used as server
application it has to be started with the command line option @code{-b}.
Since launching is done using @code{rsh}, the host on which the
application should run must have an entry in your @code{.rhosts}
file. Even the local machine must have an entry if applications should
be launched locally.

If the MPtcp link is opened in fork mode a child of the current
@sc{Singular} is forked. All variables and their values are inherited by
the child. The child acts as a server whereas the @sc{Singular} that
actually opened the link acts as a client.

To arrange the evaluation of an expression by a server, the expression
must be quoted using the command @code{quote} (see @ref{quote}), so that
a local evaluation is prevented (otherwise, the expression is evaluated
first, and the result of the evaluation is written, instead of the
expression which is to be evaluated).

If @sc{Singular} is in server mode, the value of the variable
@code{mp_ll} is the MPtcp link connecting to the client and
@sc{Singular} is in an infinite read-eval-write loop until the
connection is closed from the client side (by closing its connecting
link). Reading and writing is done to the link @code{mp_ll} -- after an
expression is read, it is evaluated and the result of the evaluation is
written back.  That is, for each expression which was written to the
server, there is exactly one expression written back (which might be an
"empty" expression, if the evaluation on the server side does not return
a value).

MPtcp links should explicitly be opened before being used. MPtcp links
are bidirectional, i.e., can be be used for both, writing and
reading. Reading from an MPtcp link blocks until data was written to
that link. The @code{status} command can be used to check whether there
is data to read.

@strong{Example:}
@example
@c example
  LIB "general.lib"; // needed for "which" and "killall" commands
  // MPtcp:launch link for launching SINGULAR in batch modus
  // on the local host 
  link l="MPtcp:launch";
  open(l);
  l; // notice that link is ready for writing but not for reading
  ring r; ideal i=x2+y,xyz+z,x2+y2;
  write (l,quote(std(eval(i)))); // std(i) is computed on server
  // server wrote result back -- ready for reading
  def j = read(l);   // result of computation on server is read
  j;
  write(l, quote(std(i)));
                     // std of polynomial "i" is computed on server
  def k = read(l);   // result of computation is read
  k; basering;       // notice that a new ring was created and set
  listvar(all);
  write(l, killall); read(l);
                     // write killall procedure to server
  // and kill everything in server, but links (need to protect mp_ll)
  write(l, quote(killall("not", "link"))); read(l);
  write(l, quote(getdump(mp_ll))); // server gets dump
  dump(l);           //  dump is written to server (includes proc's)
  read(l);           // result of previous write-command is read
  killall("not", "link"); killall("proc");
                     // kills eveything, but links
  write(l, quote(dump(mp_ll))); // server writes dump
  getdump(l);        // dump is read from server
  read(l);           // result of previous write-command is read
  close(l);          // server is shut down
  listvar(all);      // same state as we had before "killall()"
  l = "MPtcp:";      // fork link declaration
  open(l); l;        // Notice that name is "parent"
  // and name of forked link is "child"
  write(l, quote(status(mp_ll, "name")));
  read(l);
  write(l, quote(i)); // Child inherited vars and their values
  read(l);
  close(l);          // shut down forked child
@c example
@end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ------------------------------
@node DBM links,  , MP links, link
@subsection DBM links
@cindex DBM links

@c {{{ subsection DBM links }}}
DBM links provide access to data stored in a data base (using the dbm or
gdbm library). Each entry in the data base consists of a (key_string,
value_string) pair. Such a pair can be inserted with the command
@code{write(}link@code{,} key_string@code{,} value_string@code{)}.  By
calling @code{write(}link@code{,} key_string@code{)}, the entry with key
key_string is deleted from the data base. The value of an entry is
returned by the command @code{read(}link@code{,}
key_string@code{)}. With only one argument, @code{read(}link@code{)}
returns the next key in the data base. Using this feature you can scan a
data base in order to access all entries of the data base.

If a data base with name @code{name} is opened for writing for the first
time, two files (@code{name.pag} and @code{name.dir}) are automatically
created, which contain the data base. 

The DBM link describing string has to be one of the following:

@enumerate
@item @code{"DBM: "} + name
@*opens the data base for reading (default mode).

@item @code{"DBM:r "} + name
@*opens the data base for reading.

@item @code{"DBM:rw "} + name
@*opens the data base for reading and writing.
@end enumerate

Note, that @code{name} without the suffix @code{.pag} or @code{.dir} is
the name of the data base which is used for DBM links (see the example
below). The name may contain an (absolute) path.

@strong{Example:}
@example
@c example
  link l="DBM:rw example";
  write(l,"1","abc");
  write(l,"3","XYZ");
  write(l,"2","ABC");
  l;
  close(l);
  // read all keys (till empty string):
  read(l);
  read(l);
  read(l);
  read(l);
  // read data corresponding to key "1"
  read(l,"1");
  // read all data:
  read(l,read(l));
  read(l,read(l));
  read(l,read(l));
  // close
  close(l);
@c example
@end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node list, map, link, Data types
@section list
@cindex list

@c {{{ section list }}}
@menu
* list declarations::
* list expressions::
* list operations::
* list related functions::
@end menu

Lists are arrays whose elements can be of any type
(including ring/qring). If one element belongs to a ring the whole list
belongs to that ring.
(This applies also to the special list @code{#}.)
@*Note that a list stores the objects itself and not the names.
Hence, if @code{L} is a list, @code{L[1]} for example has no name.
You can create a name, say @code{R}, for @code{L[1]} by @code{def R=L[1];}.
If you want to store also the name of an object,
say @code{r}, you may add it to the list with @code{nameof(r);}.
Objects of a list may be rings. If @code{L[1]} is a ring, you may
define @code{L[1]} to be the basering for instance by
@code{setring L[1];}.
@*Note: Unlike other assignments a ring as an element of a list
is not a copy but another reference to the same ring.
@*Note: @code{list()} is the empty list, see @ref{Type conversion and casting}.

@c ------------------------------
@node list declarations, list expressions, list, list
@subsection list declarations
@cindex list declarations

@c {{{ subsection list declarations }}}
@table @code
@item @strong{Syntax:}
@code{list} name @code{=} expression_list@code{;}
@*@code{list} name @code{=} list_expression@code{;}
@item @strong{Purpose:}
defines a list (of objects of possibly different types).
@item @strong{Default:}
empty list
@item @strong{Example:}
@example
@c example
  list l=1,"str";
  l[1];
  l[2];
  ring r;
  ideal i = x^2, y^2 + z^3;
  l[3] = i;
  l;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node list expressions, list operations, list declarations, list
@subsection list expressions
@cindex list expressions

@c {{{ subsection list expressions }}}
A list expression is:
@enumerate
@item
an identifier of type list
@item
a function returning list
@item
list expressions combined by arithmetic operation @code{+} and @code{,}
@item
a typecast to list
@item
the empty list @code{list()}
@end enumerate
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node list operations, list related functions, list expressions, list
@subsection list operations
@cindex list operations

@c {{{ subsection list operations }}}
@table @asis
@item @code{+}
concatenation
@item @code{,}
construct a new list whose elements are the parts of the expression list
@end table
Brackets may be used to access elements of lists:
@emph{list expressions} @code{[} @emph{int expressions} @code{]} is a list entry.
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}

@c ------------------------------
@node list related functions, ,list operations, list
@subsection list related functions
@cindex list related functions

@c {{{ subsection list related functions }}}
@table @asis
@item @code{betti}
Betti numbers from a resolution (see @ref{betti})
@item @code{delete}
delete an element from a list (see @ref{delete})
@item @code{facstd}
factorizing Groebner basis algorithm (see @ref{facstd})
@item @code{insert}
insert or append a new element to a list (see @ref{insert})
@item @code{minres}
minimize a free resolution (see @ref{minres})
@item @code{mres}
minimal free resolution of an ideal/module, also
minimizing the first module (see @ref{mres})
@item @code{names}
list of all userdefined variable names (see @ref{names})
@item @code{res}
minimal free resolution of an ideal/module (see @ref{res})
@item @code{size}
number of entries (see @ref{size})
@item @code{sres}
free resolution of an ideal/module given by a standard base (see @ref{sres})
@end table
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node map, matrix, list, Data types
@section map
@cindex map

@c {{{ section map }}}
@menu
* map declarations::
* map expressions::
* map related functions::
@end menu

Maps are ring maps from a preimage ring into the base ring.
Note that the target of a map is ALWAYS the actual base ring.
Maps between rings with different coefficient fields are
possible, the map of the coefficients is defined in the following way:
@table @asis
@item Z/p -> Q
@tex
$[i]_p \rightarrow i \in [-p/2,p/2] \subseteq $Z
@end tex
@ifinfo
[i]_p -> i in [-p/2,p/2] in Z
@end ifinfo
@item Z/p -> Z/p'
@tex
$[i]_p \in $Z/p$ \rightarrow i \in [-p/2,p/2] \subseteq $Z$ \rightarrow [i]_{p'} \in $Z/p'
@end tex
@ifinfo
[i]_p in Z/p -> i in [-p/2,p/2] in Z -> [i]_p' in Z/p'
@end ifinfo
@item Q -> Z/p
@itemx Q -> (Z/p)(a,..)
@itemx Q -> Q(a,..)
@itemx Z/p ->(Z/p)(a,...)
as usual
@end table

@c ref
See @ref{imap}; @ref{fetch}; @ref{subst}.
@c ref

@c ------------------------------
@node map declarations, map expressions, map, map
@subsection map declarations
@cindex map declarations

@c {{{ subsection map declarations }}}
@table @code
@item @strong{Syntax:}
@code{map} name @code{=} preimage_ring_name @code{,} ideal_expression @code{;}
@item @strong{Purpose:}
define a ring map from preimage_ring to basering
@sp 1
map the variables of the preimage ring to the generators of the ideal.
If the ideal contains less elements than variables in the
preimage_ring the remaining variables are maped to 0, if the ideal contains
more elements these are ignored.
The image ring is always the actual base ring.
For the mapping of coefficients from different fields see @ref{map}.
@item @strong{Default:}
none
@*Maps may be composed.
@item @strong{Remark:}
There are standard mappings for the identity map: @code{fetch} and @code{imap}.
@item @strong{Example:}
@example
@c example
  ring r1=32003,(x,y,z),dp;
  ideal i=x,y,z;
  ring r2=32003,(a,b),dp;
  map f=r1,a,b,a+b;
  // maps from r1 to r2,
  // x to a, y to b and z to a+b
  f(i);
  // operations like f(i[1]) or f(i*i) are not allowed
  ideal i=f(i);
  // objects in different rings may have the same name
  map g   = r2,a2,b2;
  map phi = g(f);
  // composition of map f and g
  // maps from r1 to r2,
  // x to a2, y to b2, z to a2+b2
  phi(i);
@c example
@end example
@end table
@c ref
See @ref{map}; @ref{ideal expressions}; @ref{ring};
@ref{imap}; @ref{fetch}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node map expressions, map related functions, map declarations, map
@subsection map expressions
@cindex map expressions

@c {{{ subsection map expressions }}}
A map expression is:
@enumerate
@item
an identifier of type map
@item
a function returning map
@item
map expressions combined by composition
@end enumerate
@c {{{endfold}}}

@c @c ------------------------------
@c @node map operations, map related functions, map expressions, map
@c @subsection map operations
@c @cindex map operations
@c

@c ------------------------------
@node map related functions,  , map expressions, map
@subsection map related functions
@cindex map related functions

@c {{{ subsection map related functions }}}
@strong{Apply a map:}
the name of a map serves as the function which maps objects from the
preimage_ring into the base ring.  These objects must be defined
by names (no evaluation in the preimage ring is possible).
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node matrix, module, map, Data types
@section matrix
@cindex matrix

@c {{{ section matrix }}}
@menu
* matrix declarations::
* matrix expressions::
* matrix operations::
* matrix related functions::
@end menu

Matrices are matrices with polynomial entries.
Like polynomials they
can only be defined or accessed with respect to a base ring.
If you wish to compute with matrices having integer or rational entries
define a ring with characteristic 0 and one variable.

If A is a matrix then the assignment @code{module M=A;} or
@code{module M=module(A);} creates a module generated by the columns of A.
Note that the trailing zero columns of A may be deleted by module operations with M.

@c ------------------------------
@node matrix declarations, matrix expressions, matrix, matrix
@subsection matrix declarations
@cindex matrix declarations

@c {{{ subsection matrix declarations }}}
@table @code
@item @strong{Syntax:}
@code{matrix} name@code{[}rows@code{][}cols@code{] =} list_of_poly_expressions @code{;}
@*@code{matrix} name = matrix_expression @code{;}
@item @strong{Purpose:}
defines a matrix (of polynomials).

The given poly_list fills up the matrix beginning with the first row
from the left to the right, then the second row and so on.
If the poly_list contains less than rows*cols elements,
the matrix is filled up with zeros; if it contains more
elements, then only the first rows*cols elements are used.
If the right-hand side is a matrix expression
the matrix on the left-hand side becomes the same size as the right-hand side,
otherwise the size is determined by the left-hand side.
If the size is omitted a 1x1 matrix will be created.
@item @strong{Default:}
0 (1 x 1 matrix)
@item @strong{Example:}
@example
@c example
  int ro = 3;
  ring r = 32003,(x,y,z),dp;
  poly f=xyz;
  poly g=z*f;
  ideal i=f,g,g^2;
  matrix m[ro][3] = 1x3y4, 0, i, f ; // a 3 x 3 matrix
  m;
  print(m);
  matrix A;   // the 1 x 1 zero matrix
  matrix B[2][2] = m[1..2, 2..3]; //defines a submatrix
  print(B);
  matrix C=m; // defines C as a 3 x 3 matrix equal to m
  print(C);
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node matrix expressions, matrix operations, matrix declarations, matrix
@subsection matrix expressions
@cindex matrix expressions

@c {{{ subsection matrix expressions }}}
A matrix expression is:
@enumerate
@item
an expression list of poly expressions
@item
an identifier of type matrix
@item
a function returning matrix
@item
matrix expressions combined by arithmetic operations @code{+,-,*}
@item
a typecast to matrix.
@end enumerate
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node matrix operations, matrix related functions, matrix expressions, matrix
@subsection matrix operations
@cindex matrix operations

@c {{{ subsection matrix oparations }}}
@table @asis
@item @code{+}
addition
@item @code{-}
negation or subtraction
@item @code{*}
multiplication (with poly, matrix)
@item @code{==}, @code{<>}
comparison
@end table
Brackets may be used to access elements of matrices:
@emph{matrix expressions} @code{[} @emph{row}@code{,} @emph{column} @code{]} is a matrix entry.
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}

@c ------------------------------
@node matrix related functions, ,matrix operations, matrix
@subsection matrix related functions
@cindex matrix related functions

@c {{{ subsection matrix related functions }}}
@table @asis
@item @code{bareiss}
Bareiss algorithm (see @ref{bareiss})
@item @code{coef}
matrix of coefficients and monomials (see @ref{coef})
@item @code{coeffs}
matrix of coefficients (see @ref{coeffs})
@item @code{det}
determinant (see @ref{det})
@item @code{diff}
partial derivative (see @ref{diff})
@item @code{jacob}
Jacobi matrix (see @ref{jacob})
@item @code{koszul}
Koszul matrix (see @ref{koszul})
@item @code{lift}
lift-matrix (see @ref{lift})
@item @code{liftstd}
standardbasis and transformation matrix computation (see @ref{liftstd})
@item @code{minor}
set of minors of a matrix (see @ref{minor})
@item @code{ncols}
number of columns (see @ref{ncols})
@item @code{nrows}
number of rows (see @ref{nrows})
@item @code{size}
number of matrix entries (see @ref{size})
@item @code{subst}
substitute a ring variable (see @ref{subst})
@item @code{trace}
trace of a matrix (see @ref{trace})
@item @code{transpose}
transpose a matrix (see @ref{transpose})
@item @code{wedge}
wedge product (see @ref{wedge})
@end table
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node module, number, matrix, Data types
@section module
@cindex module

@c {{{ section module }}}
@menu
* module declarations::
* module expressions::
* module operations::
* module related functions::
@end menu

Modules are submodules of a free module over the base ring with basis
@code{gen(1)}, @code{gen(2)}, @dots{} .
They are represented by lists of vectors which generate the submodule.
Like vectors they
can only be defined or accessed with respect to a base ring.
If M is a submodule of
@ifinfo
R^n,
@end ifinfo
@tex
R$^n,$
@end tex
R the base ring, generated by vectors
@ifinfo
v_1, @dots{}, v_k, then v_1, @dots{}, v_k
@end ifinfo
@tex
$v_1, \ldots, v_k$, then $v_1, \ldots, v_k$
@end tex
may be considered as the generators of relations of
@ifinfo
R^n/M
@end ifinfo
@tex
R$^n$/M
@end tex
between the canonical generators @code{gen(1)},@dots{},@code{gen(n)}.
Hence any finitely generated R-module can be represented in @sc{Singular}
by its module of relations. The assignments
@code{module M=v1,...,vk; matrix A=M;}
creates the presentation matrix of size n x k for
@ifinfo
R^n/M,
@end ifinfo
@tex
R$^n$/M,
@end tex
i.e. the columns of A are the vectors
@ifinfo
v_1, @dots{}, v_k
@end ifinfo
@tex
$v_1, \ldots, v_k$
@end tex
which generate M.

@c ------------------------------
@node module declarations, module expressions, module, module
@subsection module declarations
@cindex module declarations

@c {{{ subsection module declarations }}}
@table @code
@item @strong{Syntax:}
@code{module} name @code{=} list_of_vector_expressions @code{;}
@*@code{module} name @code{=} module_expression @code{;}
@item @strong{Purpose:}
defines a module.
@item @strong{Default:}
[0]
@item @strong{Example:}
@example
@c example
  ring r=0,(x,y,z),(c,dp);
  vector s1 = [x2,y3,z];
  vector s2 = [xy,1,0];
  vector s3 = [0,x2-y2,z];
  poly   f  = xyz;
  module m = s1, s2-s1,f*(s3-s1);
  m;
  // show m in matrix format (columns generate m)
  print(m);
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node module expressions, module operations, module declarations, module
@subsection module expressions
@cindex module expressions

@c {{{ subsection module expressions }}}
A module expression is:
@enumerate
@item
an expression list of vector expressions
@item
an identifier of type module
@item
a function returning module
@item
module expressions combined by the arithmetic operation @code{+}
@item
multiplication of a module expressions with an ideal or poly expression (@code{*})
@item
a typecast to module.
@end enumerate
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node module operations, module related functions, module expressions, module
@subsection module operations
@cindex module operations

@c {{{ subsection module oparations }}}
@table @asis
@item @code{+}
addition (concatenation of the generators and simplification)
@item @code{*}
multiplication with ideal or poly, but not `module` * `module`
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}

@c ------------------------------
@node module related functions, ,module operations, module
@subsection module related functions
@cindex module related functions

@c {{{ subsection module related functions }}}
@table @asis
@item @code{coeffs}
matrix of coefficients (see @ref{coeffs})
@item @code{degree}
multiplicity, dimension and codimension of the module of leading terms (see @ref{degree})
@item @code{diff}
partial derivative (see @ref{diff})
@item @code{dim}
Krull dimension of free module over the base ring modulo the module of leading terms (see @ref{dim})
@item @code{eliminate}
elimination of variables (see @ref{eliminate})
@item @code{freemodule}
the free module of given rank (see @ref{freemodule})
@item @code{hilb}
Hilbert function of a standardbasis (see @ref{hilb})
@item @code{homog}
homogenization with respect to a variable (see @ref{homog})
@item @code{interred}
interreduction of a module (see @ref{interred})
@item @code{intersect}
module intersection (see @ref{intersect})
@item @code{jet}
k-jet: Taylor series up to a given order (see @ref{jet})
@item @code{kbase}
vector space basis of free module over the basering modulo standardbasis (see @ref{kbase})
@item @code{lead}
initial module (see @ref{lead})
@item @code{lift}
lift-matrix (see @ref{lift})
@item @code{liftstd}
standardbasis and transformation matrix computation (see @ref{liftstd})
@item @code{minbase}
minimal generating set of a homogeneous ideal/module or an ideal/module
over a local ring
(see @ref{minbase})
@item @code{modulo}
represents (h1+h2)/h1=h2/(h1 intersect h2) (see @ref{modulo})
@item @code{mres}
minimal free resolution of an ideal/module, also minimizing the given module
(see @ref{mres})
@item @code{mult}
multiplicity of a module (see @ref{mult})
@item @code{ncols}
number of columns (see @ref{ncols})
@item @code{nrows}
number of rows (see @ref{nrows})
@item @code{prune}
minimize the embedding into a free module (see @ref{prune})
@item @code{qhweight}
quasihomogeneous weights of an ideal/module (see @ref{qhweight})
@item @code{quotient}
ideal quotient (see @ref{quotient})
@item @code{reduce}
normalform with respect to a standardbasis (see @ref{reduce})
@item @code{res}
minimal free resolution of an ideal/module but not changing the given ideal/module
(see @ref{res})
@item @code{simplify}
simplify a set of vectors (see @ref{simplify})
@item @code{size}
number of non-zero generators (see @ref{size})
@item @code{sortvec}
permutation for sorting ideals/modules (see @ref{sortvec})
@item @code{sres}
free resolution of a standard basis (see @ref{sres})
@item @code{std}
standardbasis computation (see @ref{std}, @ref{liftstd})
@item @code{subst}
substitute a ring variable (see @ref{subst})
@item @code{syz}
computation of the first syzygy module (see @ref{syz})
@item @code{vdim}
vector space dimension of free module over the basering modulo module (see @ref{vdim})
@item @code{weight}
"optimal" weights (see @ref{weight})
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node number, poly, module, Data types
@section number
@cindex number

@c {{{ section number }}}
@c ------------------------------
@menu
* number declarations::
* number expressions::
* number operations::
@end menu

Numbers are the coefficients of a monomial (power products of ring variables).
They can only be defined or accessed with respect to a base ring
which determines the coefficient field.
@example
@c example
  ring r0=32003,x,dp;
  number n=2/3; n;
  ring r1=0,x,dp;
  number n=2/3; n;
  ring r2=(0,a),(x,y,z),dp;
  number n=2/3; n;
  n=a+a^2;
  poly f=n*x+2;f;
@c example
@end example

@node number declarations, number expressions, number, number
@subsection number declarations
@cindex number declarations

@c {{{ subsection number declarations }}}
@table @code
@item @strong{Syntax:}
@code{number} name @code{=} number_expression @code{;}
@item @strong{Purpose:}
defines a number.
@item @strong{Default:}
0
@item @strong{Example:}
@example
@c example
  ring r = 32003,(x,y,z),dp;
  number n = 4/6;
  n;
  ring r0 = 0,x,dp;
  number n = 4/6;
  n;
  ring R=real,x,dp;
  number n=4/6;
  n;
  n=0.25e+2;
  n;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node number expressions, number operations, number declarations, number
@subsection number expressions
@cindex number expressions

@c {{{ subsection number expressions }}}
A number expression is:
@enumerate
@item
a rational number (there are NO spaces allowed inside a rational number,
see @ref{int expressions})
@item
a floating point number (if the coefficient field is @code{real}):
@*<digits>@code{.}<digits>@code{e}<sign><digits>
@item
an identifier of type number
@item
a function returning number (see @ref{number operations})
@item
an int expression (see @ref{Type conversion and casting})
@item
number s combined by arithmetic operations @code{+,-,*,/} or @code{^,**}.
(see @ref{number operations}).
@end enumerate

@strong{Example:}
@example
  2/3, 4/8, 2/2 ; // are numbers
  2 / 3, 4/ 8,  2 /2 ; // are int expressions (of value 0, 0 and 1)
  1.7e-2; 1.7e+2 // are valid (but  1.7e2 not), if the field is `real`
@end example
@c ref
See @ref{number}; @ref{ring}; @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node number operations, , number expressions, number
@subsection number operations
@cindex number operations

@c {{{ subsection number operations }}}
@table @asis
@item @code{+}
addition
@item @code{-}
negation resp. subtraction
@item @code{*}
multiplication
@item @code{/}
division
@item @code{^,**}
power, exponentiation (by an integer)
@item @code{<=, >=, ==, <>}
comparison
@item @code{leadcoef}
coefficient of the leading term (see @ref{leadcoef})
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node poly, proc, number, Data types
@section poly
@cindex poly

@c {{{ section poly }}}
@menu
* poly declarations::
* poly expressions::
* poly operations::
* poly related functions::
@end menu

Polynomials are the basic data for all main algorithms in @code{@sc{Singular}}.
They consist of finitely many terms (coefficient*power product)
which are combined by the usual
polynomial operations (see @ref{poly expressions}).
Polynomials can only be defined or accessed with respect to a base ring
which determines the coefficient type, the names of the indeterminants and the
monomial ordering.
@example
@c example
  ring r=32003,(x,y,z),dp;
  poly f=x3+y5+z2;
@c example
@end example

@c ------------------------------
@node poly declarations, poly expressions, poly, poly
@subsection poly declarations
@cindex poly declarations

@c {{{ subsection poly declarations }}}
@table @code
@item @strong{Syntax:}
@code{poly} name @code{=} poly_expression @code{;}
@item @strong{Purpose:}
defines a polynomial.
@item @strong{Default:}
0
@item @strong{Example:}
@example
  ring r = 32003,(x,y,z),dp;
  poly s1  = x3y2+151x5y+186xy6+169y9;
  poly s2  = 1*x^2*y^2*z^2+3z8;
  poly s3  = 5/4x4y2+4/5*x*y^5+2x2y2z3+y7+11x10;
  int a,b,c,t=37,5,4,1;
  poly f=3*x^a+x*y^(b+c)+t*x^a*y^b*z^c;
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node poly expressions, poly operations, poly declarations, poly
@subsection poly expressions
@cindex poly expressions

@c {{{ subsection poly expressions }}}
A poly expression is (optional parts in square brackets):
@enumerate
@item
a monomial (there are NO spaces allowed inside a monomial)
@example
  [coefficient] ring_variable [ exponent] [ring_variable [exponent] @dots{}]
@end example
monomials which contain an indexed ring variable
must be built from @code{ring_variable} and @code{coefficient}
with the operations * and ^
@item
an identifier of type poly
@item
a function returning poly (see @ref{poly related functions})
@item
an int expression (see @ref{Type conversion and casting})
@item
poly expressions combined by arithmetic operations +,-,*,/ or ^.
(see @ref{poly operations}).
@end enumerate

@strong{Example:}
@example
  2x, x3, 2x2y3, xyz, 2xy2; //  are monomials
  2*x, x^3, 2*x^2*y^3, x*y*z, 2*x*y^2; // are poly expressions
  2*x(1); // is a valid poly expression, but not 2x(1) (a syntax error)
  2*x^3; //  is a valid poly expression equal to 2x3 (a valid monomial)
         // but not equal to 2x^3
         // which will be interpreted as (2x)^3
@end example
@c ref
See @ref{ring}; @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node poly operations, poly related functions, poly expressions, poly
@subsection poly operations
@cindex poly operations

@c {{{ subsection poly operations }}}
@table @asis
@item @code{+}
addition
@item @code{-}
negation resp. subtraction
@item @code{*}
multiplication
@item @code{/}
division by a monomial, non divisible terms yield 0
@item @code{^,**}
power by an integer
@item @code{<}, @code{<=}, @code{>}, @code{>=}, @code{==}, @code{<>}
comparison
@item @code{[}, @code{]}
choice of the monomial at the indicated place w.r.t. the monomial order
@end table
@*
Brackets may be used to access elements of ideals and matrices:
@emph{ideal expressions} @code{[} @emph{position} @code{]} is a generator of the ideal,
@emph{matrix expressions} @code{[} @emph{row}@code{,} @emph{column} @code{]} is a matrix entry.

@strong{Example:}
@example
@c example
  ring R=0,(x,y),dp;
  x+y;
  x<=y;
  (x+y+x^2)[2]; // the 2nd biggest monomial
  (x+y)/x;
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node poly related functions, ,poly operations, poly
@subsection poly related functions
@cindex poly related functions

@c {{{ subsection poly related functions }}}
@table @asis
@item @code{cleardenom}
quotient of a poly by its content (see @ref{cleardenom})
@item @code{coef}
matrix of coefficients and monomials (see @ref{coef})
@item @code{coeffs}
matrix of coefficients (see @ref{coeffs})
@item @code{deg}
degree (see @ref{deg})
@item @code{det}
determinant (see @ref{det})
@item @code{diff}
partial derivative (see @ref{diff})
@item @code{finduni}
find univariate polynomials in a zero dimensional ideal (see @ref{finduni})
@item @code{homog}
homogenization (see @ref{homog})
@item @code{jacob}
ideal resp. matrix of all partial derivatives (see @ref{jacob})
@item @code{lead}
leading monomial (see @ref{lead})
@item @code{leadcoef}
coefficient of the leading term (see @ref{leadcoef})
@item @code{leadexp}
the exponent vector of the leading monomial (see @ref{leadexp})
@item @code{jet}
monomials with degree smaller k+1 (see @ref{jet})
@item @code{ord}
degree of the leading monomial (see @ref{ord})
@item @code{reduce}
normal form with respect to a standard base (see @ref{reduce})
@item @code{rvar}
test for ring variable (see @ref{rvar})
@item @code{simplify}
normalize a polynomial (see @ref{simplify})
@item @code{size}
number of monomials (see @ref{size})
@item @code{subst}
substitute a ring variable (see @ref{subst})
@item @code{trace}
trace of a matrix (see @ref{trace})
@item @code{var}
the indicated variable of the ring (see @ref{var})
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node proc, qring, poly, Data types
@section proc
@cindex proc

See @ref{Procedures}.

@c ---------------------------------------
@node qring, resolution, proc, Data types
@section qring
@cindex qring

@c {{{ section qring }}}
@table @code
@item @strong{Syntax:}
@code{qring} name @code{=} ideal_expression @code{;}
@item @strong{Purpose:}
defines a quotient ring as the base ring modulo an ideal.

The ideal must be a standard basis. The qring command performs a change
of the base ring to this new ring.
@item @strong{Default:}
none
@item @strong{Example:}
@example
@c example
  ring r1=32003,(x,y,z),dp;
  ideal i=std(ideal(x,y));
  qring q=i;
  basering;
  std(ideal(x+y,x+y+z,z));
@c example
@end example
@end table
@c {{{endfold}}}

@c ---------------------------------------
@node resolution, ring, qring, Data types
@section resolution
@cindex resolution

@c {{{ section resolution }}}
@menu
* resolution declarations::
* resolution expressions::
* resolution related functions::
@end menu

Resolutions are represented as lists of ideals/modules which generate the
resolution.
Like ideals/modules they
can only be defined or accessed with respect to a base ring.
@c ---------------------------------------
@node resolution declarations, resolution expressions, resolution, resolution
@subsection resolution declarations
@cindex resolution declarations

@c {{{ subsection resolution daclarations }}}
@table @code
@item @strong{Syntax:}
@code{resolution} name @code{=} resolution_expression @code{;}
@item @strong{Purpose:}
defines a resolution.
@item @strong{Default:}
none
@item @strong{Example:}
@example
@c example
  ring R;
  ideal i=z2,x;
  resolution re=res(i,0);
  re;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node resolution expressions, resolution related functions, resolution declarations, resolution
@subsection resolution expressions
@cindex resolution expressions

@c {{{ subsection resolution expressions }}}
A resolution expression is:
@enumerate
@item
an identifier of type resolution
@item
a function returning resolution
@item
a typecast from list to resolution.
@end enumerate
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node resolution related functions, ,resolution expressions, resolution
@subsection resolution related functions
@cindex resolution related functions

@c {{{ subsection resolution related functions }}}
@table @asis
@item @code{mres}
minimal free resolution of an ideal/module, also minimizing the given ideal/module
(see @ref{mres})
@item @code{res}
minimal free resolution of an ideal/module but not changing the given ideal/module
(see @ref{res})
@item @code{sres}
free resolution of a standard basis (see @ref{sres})
@end table
@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node ring, string, resolution, Data types
@section ring
@cindex ring

@c {{{ section ring }}}
Rings are ... . See @ref{Rings and orderings}.

@menu
* ring declarations::
@end menu

@node ring declarations,  , ring, ring
@subsection ring declarations
@cindex ring declarations

@c {{{ subsection ring declarations }}}
@c ------------------------------------------------------------
@c   This piece of text exists also in the file general.doc, 
@c   chapter "General syntax of a ring declaration".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
@table @code
@item @strong{Syntax:}
@code{ring} name @code{=} field@code{,}
@code{(} names_of_ring_variables @code{),}
@code{(} ordering @code{);}
@item @strong{Default:}
@code{32003,(x,y,z),(dp,C);}
@item @strong{Purpose:}
defines a base ring for polynomials, ideals, vectors, modules, resolutions
and matrices and sets it as the actual basering.

The coefficient field is given by either
@enumerate
@item
the characteristic (0 or a prime <= 32003)
@item
an expression_list of the characteristic and
the names of parameters
@item
an expression_list of the number of elements
(a small prime characteristic p to the power of a small exponent n) and a
name for a primitive element
@item
@code{real}
@end enumerate

The names of ring variables are like variable names (comma separated).

The ordering is a list of blockorderings which have an order keyword and
a weight vector or an optional size.

Possible order keywords are:
@itemize @bullet
@item @code{lp}, @code{dp}, @code{Dp}, @code{ls}, @code{ds}, @code{Ds}, @code{M}
with optional size parameter

@item @code{wp}, @code{Wp}, @code{ws}, @code{Ws}
with weight vector

@item @code{c}, @code{C}
for components orders

@end itemize

If one element of the list consists of only one entry, the parentheses may
be omitted.

@item @strong{Example: }
@example
@c example
  ring r=0,(a,b,c,d),dp;
  r;
@c example
@end example
@end table
@c {{{endfold}}}
@c {{{endfold}}}


@c ---------------------------------------
@node string, vector, ring, Data types
@section string
@cindex string

@c {{{ section string }}}
@menu
* string declarations::
* string expressions::
* string operations::
* string related functions::
@end menu

Variables of type @code{string} are used for output (almost every type can be
"converted"
to @code{string}) and for building your own commands at runtime
(see @ref{execute}).
They are also return values of certain interpreter related functions
(see @ref{Functions}).
String constants consist of a sequence of ANY characters
(including newline!) between a starting @code{"} and a closing @code{"}.
There is also a string constant @code{newline}, which is the newline character.
The @code{+} sign "adds" strings, @code{""} is the empty string
(hence strings form a semigroup). Strings may be used to comment
the output of a computation or to give it a nice format.
Strings may also be used
to convert one type into another.
@example
@c example
  string s="Hi";
  string s1="a string with new line at the end"+newline;
  string s2="another string with new line at the end
  ";
  s;s1;s2;
  ring r; ideal i=std(ideal(x,y^3));
  "dimension of i =",dim(i),", multiplicity of i =",mult(i);
  "dimension of i = "+string(dim(i))+", multiplicity of i = "+string(mult(i));
  "a"+"b","c";
@c example
@end example
A comma between two expressions makes an expression list out of them
(such a list is printed with as a separating blank between),
while a @code{+} concatenates strings.

@c ------------------------------
@node string declarations, string expressions, string, string
@subsection string declarations
@cindex string declarations

@c {{{ subsection string declarations }}}
@table @code
@item @strong{Syntax:}
@code{string} name @code{=} string_expression @code{;}
@item @strong{Purpose:}
defines a string variable.
@item @strong{Default:}
"" (the empty string)
@item @strong{Example:}
@example
@c example
  string s1="Now I know";
  string s2="how to encode a \" in a string...";
  string s=s1+" "+s2; // concatenation of 3 strings
  s;
  s1,s2;   // 2 strings, separated by a blank in the output:
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node string expressions, string operations, string declarations, string
@subsection string expressions
@cindex string expressions

@c {{{ subsection string expressions }}}
A string expression is:
@enumerate
@item
a sequence of characters between two quotes (@code{"})
@item
an identifier of type string
@item
a function returning string
@item
a substring
@item
a typecast to string (from any type)
@item
string expressions combined by the operation @code{+}.
@end enumerate

@strong{Example:}
@example
  // a string constant
  "@dots{}";
  // a typecast from name
  string(name)
  // concatenation
  string_expression + string_expression
  //string_expression[start, length] : a substring
  //(possibly filled up with blanks)
  string s="123456";
  s[2,4];// the substring of s starting at position 2
         // with a length of 4
  @expansion{} 2345
  "abcd"[2,2];
  @expansion{} bc
  //string_expression[position] : a character from a string
  s[3];
  @expansion{} 3
  //a function returning a string
  typeof(s);
  @expansion{} string
@end example
@c ref
See @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node string operations, string related functions, string expressions, string
@subsection string operations
@cindex string operations

@c {{{ subsection string operations }}}
@table @asis
@item @code{+}
concatenation
@item @code{<=}, @code{>=}, @code{==}, @code{<>}
comparison (lexicographic with respect to the ASCII coding)
@end table
@*
Brackets may be used to access parts of a string:
@emph{string expressions} @code{[} @emph{position} @code{]} is a character of the string,
@emph{string expressions} @code{[} @emph{position}@code{,} @emph{length} @code{]} is a substring
and @emph{string expressions} @code{[} @emph{intvec} @code{]} is a list of characters
from the string.

@strong{Example:}
@example
@c example
  string s="abcde";
  s[2];
  s[3,2];
  ">>"+s[1,10]+"<<";
  s[2]="BC"; s;
  intvec v=1,3,5;
  s=s[v]; s;
  s="123456"; s=s[3..5]; s;
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node string related functions, ,string operations, string
@subsection string related functions
@cindex string related functions

@c {{{ subsection string related functions }}}
@table @asis
@item @code{nameof}
name of an object (see @ref{nameof})
@item @code{read}
read a file (see @ref{read})
@item @code{size}
length of a string (see @ref{size})
@item @code{find}
position of a substring in a string (see @ref{find})
@item @code{typeof}
type of an object (see @ref{typeof})
@item @code{ordstr}
monomial ordering of a ring (see @ref{ordstr})
@item @code{charstr}
description of the coeffinet field of a ring (see @ref{charstr})
@item @code{parstr}
names of all ring parameters or the
name of the n-th ring parameter (see @ref{parstr})
@item @code{varstr}
names of all ring variables or the
name of the n-th ring variable (see @ref{varstr})
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c ---------------------------------------
@node vector,  , string, Data types
@section vector
@cindex vector

@c {{{ section vector }}}
@menu
* vector declarations::
* vector expressions::
* vector operations::
* vector related functions::
@end menu

Vectors are elements of a free module over the basering with basis
@code{gen(1)}, @code{gen(2)}, @dots{} .
Each vector belongs to a free module of rank equal to the biggest index
of a generator with nonzero coefficient. Since generators with zero
coefficients need not be written any vector may be considered
also as an element of a free module of higher rank.
Like polynomials they
can only be defined or accessed with respect to this base ring.
(E.g. if @code{f} and @code{g} are polynomials then
@code{f*gen(1)+g*gen(3)+gen(4)} can also be written as @code{[f,0,g,1]}
or as @code{[f,0,g,1,0]}.)

@c ------------------------------
@node vector declarations, vector expressions, vector, vector
@subsection vector declarations
@cindex vector declarations

@c {{{ subsection vector declarations }}}
@table @code
@item @strong{Syntax:}
@code{vector} name @code{=} vector_expression @code{;}
@item @strong{Purpose:}
defines a vector of polynomials (an element of a free module).
@item @strong{Default:}
[0]
@item @strong{Example:}
@example
@c example
  ring r=0,(x,y,z),(c,dp);
  poly s1 = x2;
  poly s2 = y3;
  poly s3 = z;
  vector v = [s1, s2-s1, s3-s1]+ s1*gen(5);
  // v is a vector in the free module of rank 5
  v;
@c example
@end example
@end table
@c {{{endfold}}}

@c ------------------------------
@node vector expressions, vector operations, vector declarations, vector
@subsection vector expressions
@cindex vector expressions

@c {{{ subsection vector expressions }}}
A vector expression is:
@enumerate
@item
an identifier of type vector
@item
a function returning vector
@item
a poly expression (via the canonical embedding p -> p*gen(1))
@item
vector expressions combined by arithmetic operations @code{+} or @code{-}
@item a poly expression and a vector expression
combined by arithmetic operation @code{*}.
@end enumerate

@strong{Example:}
@example
@c example
  // ordering gives priority to components:
  ring rr=0,(x,y,z),(c,dp);
  vector v=[x2+y3,2,0,x*y]+gen(6)*x6;
  v;
  vector w=[z3-x,3y];
  v-w;
  v*(z+x);
@c example
@end example
@c ref
See @ref{ring}; @ref{Type conversion and casting}.
@c ref
@c {{{endfold}}}

@c ------------------------------
@node vector operations, vector related functions, vector expressions, vector
@subsection vector operations
@cindex vector operations

@c {{{ subsection vector operations }}}
@table @asis
@item @code{+}
addition
@item @code{-}
negation resp. subtraction
@item @code{/}
division by a monomial, not divisible terms yield 0
@item @code{<}, @code{<=}, @code{>}, @code{>=}, @code{==}, @code{<>}
comparison
@item @code{[} @code{]}
choice of a component
@end table

@strong{Example:}
@example
@c example
  ring R=0,(x,y),(c,dp);
  [x,y]-[1,x];
  [1,2,x,4][3];
@c example
@end example
@c {{{endfold}}}

@c ------------------------------
@node vector related functions, ,vector operations, vector
@subsection vector related functions
@cindex vector related functions

@c {{{ subsection vector related functions }}}
@table @asis
@item @code{cleardenom}
quotient of a vector by its content (see @ref{cleardenom})
@item @code{coeffs}
matrix of coefficients (see @ref{coeffs})
@item @code{deg}
degree (see @ref{deg})
@item @code{diff}
partial derivative (see @ref{diff})
@item @code{gen}
i-th generator (see @ref{gen})
@item @code{homog}
homogenization (see @ref{homog})
@item @code{jet}
k-jet: monomials with degree smaller k+1 (see @ref{jet})
@item @code{lead}
leading monomial (see @ref{lead})
@item @code{leadcoef}
leading coefficient (see @ref{leadcoef})
@item @code{leadexp}
the exponent vector of the leading monomial (see @ref{leadexp})
@item @code{nrows}
number of rows (see @ref{nrows})
@item @code{ord}
degree of the leading monomial (see @ref{ord})
@item @code{reduce}
normal form with respect to a standard base (see @ref{reduce})
@item @code{simplify}
normalize a vector (see @ref{simplify})
@item @code{size}
number of monomials (see @ref{size})
@item @code{subst}
substitute a ring variable (see @ref{subst})
@end table

@c @strong{Example:}
@c @example
@c @end example
@c {{{endfold}}}
@c {{{endfold}}}

@c Local Variables: ***
@c folded-file: t ***
@c page-delimiter: "^@c {{{" ***
@c fold-internal-margins: nil ***
@c End: ***