\ignore{
\documentstyle[11pt]{report}
\textwidth 13.7cm
\textheight 21.5cm
\newcommand{\myimp}{\verb+ :- +}
\newcommand{\ignore}[1]{}
\def\definitionname{Definition}

\makeindex
\begin{document}

}
\chapter{The \texttt{util} Module}
The \texttt{util} module provides general useful utility functions and predicates. This module is expected to be expanded in the future. This module must be imported before use.

\section{Utilities on Terms}
\begin{itemize}
\item \texttt{replace($Term$,$Old$,$New$) = $NewTerm$}\index{\texttt{replace/3}}: This function returns a copy of $Term$, replacing all of the occurrences of $Old$ in $Term$ by $New$.
\item \texttt{replace\_at($Term$,$Index$,$New$) = $NewTerm$}\index{\texttt{replace\_at/3}}: This function returns a copy of $Term$, replacing the argument at $Index$ by $New$. $Term$ must be a compound term.
\item \texttt{find\_first\_of($Term$,$Pattern$) = $Index$}\index{\texttt{find\_first\_of/2}}: This function returns the first index at which the argument unifies with $Pattern$. If there is no argument that unifies with $Pattern$, then this function returns -1. $Term$ must be either a list or a structure.
\item \texttt{find\_last\_of($Term$,$Pattern$) = $Index$}\index{\texttt{find\_last\_of/2}}: This function returns the last index at which the argument unifies with $Pattern$. If there is no argument that unifies with $Pattern$, then this function returns -1. $Term$ must be either a list or a structure.

\end{itemize}


\section{Utilities on Strings and Lists}
\begin{itemize}
\item \texttt{chunks\_of($List$,$K$) = $ListOfLists$}\index{\texttt{chunks\_of/2}}: This function splits $List$ into chunks, each of which has length $K$, and returns the list of the chunks. The last chunk may have less than $K$ elements if the length of $List$ is not a multiple of $K$.
\item \texttt{drop($List$,$K$) = $List$}\index{\texttt{drop/2}}: This function returns the suffix of $List$ after the first $K$ elements are dropped, or [] if $K$ is greater than the length of $List$.
\item \texttt{find($String$,$SubString$,$From$,$To$)}\index{\texttt{find/4}}: This predicate searches for an occurrence of $SubString$ in $String$, and binds $From$ to the starting index and $To$ to the ending index. On backtracking, this predicate searches for the next occurrence of $SubString$.
\item \texttt{find\_ignore\_case($String$,$SubString$,$From$,$To$)}\index{\texttt{find\_ignore\_case/4}}: This predicate is the same as \texttt{find($String$,$SubString$,$From$,$To$)}, except that it is case insensitive.
\item \texttt{join($Tokens$) = $String$}\index{\texttt{join/1}}: This function is the same as \texttt{join($Tokens$," " )}.
\item \texttt{join($Tokens$,$Separator$) = $String$}\index{\texttt{join/2}}: This function concatenates the tokens $Tokens$ into a string, adding $Separator$, which is a string or an atom, between each two tokens.
\item \texttt{lstrip($List$) = $List$}\index{\texttt{lstrip/1}}: This function is the same as \texttt{lstrip($List$,}\verb+" \t\n\r")+. 
\item \texttt{lstrip($List$,$Elms$) = $List$}\index{\texttt{lstrip/2}}: This function returns a copy of $List$ with leading  elements in $Elms$ removed.
\item \texttt{rstrip($List$) = $List$}\index{\texttt{rstrip/1}}: This function is the same as \texttt{rstrip($List$,}\verb+" \t\n\r")+.
\item \texttt{rstrip($List$,$Elms$) = $List$}\index{\texttt{rstrip/2}}: This function returns a copy of $List$ with trailing elements in $Elms$ removed.
\item \texttt{split($String$) = $Tokens$}\index{\texttt{split/1}}: This function is the same as \texttt{split($String$,}\verb+" \t\n\r")+, which uses white spaces as split characters.
\item \texttt{split($String$,$Separators$) = $Tokens$}\index{\texttt{split/2}}: This function splits $String$ into a list of tokens, using characters in the string $Separators$ as split characters. Recall that a string is a list of characters. A token is a string, so the return value is a list of lists of characters.
\item \texttt{strip($List$) = $List$}\index{\texttt{strip/1}}: This function is the same as \texttt{strip($List$,}\verb+" \t\n\r")+. 
\item \texttt{strip($List$,$Elms$) = $List$}\index{\texttt{strip/2}}: This function returns a copy of $List$ with leading and trailing elements in $Elms$ removed.
\item \texttt{take($List$,$K$) = $List$}\index{\texttt{take/2}}: This function returns the prefix of $List$ of length $K$, or $List$ itself if $K$ is greater than the length of $List$.
\end{itemize}

\section{Utilities on Matrices}
An {\it array matrix} is a two-dimensional array. The first dimension gives the number of the rows and the second dimension gives the number of the columns. A {\it list matrix} represents a matrix as a list of lists.

\begin{itemize}
\item \texttt{matrix\_multi($A$,$B$)}\index{\texttt{matrix\_multi/2}}: This function returns the product of matrices $A$ and $B$. Both $A$ and $B$ must be array matrices.
\item \texttt{transpose($A$) = $B$}\index{\texttt{transpose/1}}: This function returns the transpose of the matrix $A$. $A$ can be an array matrix or a list matrix. If $A$ is an array matrix, then the returned transpose is also an array. If $A$ is a list matrix, then the returned transpose is also a list.
\item \texttt{rows($A$) = $List$}\index{\texttt{rows/1}}: This function returns the rows of the matrix $A$ as a list.
\item \texttt{columns($A$) = $List$}\index{\texttt{rows/1}}: This function returns the columns of the matrix $A$ as a list.
\item \texttt{diagonal1($A$) = $List$}\index{\texttt{diagonal1/1}}: This function returns primary diagonal of the matrix $A$ as a list.
\item \texttt{diagonal2($A$) = $List$}\index{\texttt{diagonal2/1}}: This function returns secondary diagonal of the matrix $A$ as a list.
\item \texttt{array\_matrix\_to\_list\_matrix($A$) = $List$}\index{\texttt{array\_matrix\_to\_list\_matrix/1}}: This function converts the array matrix $A$ to a list matrix.
\item \texttt{array\_matrix\_to\_list($A$) = $List$}\index{\texttt{array\_matrix\_to\_list/1}}: This function converts the array matrix $A$ to a flat list, row by row.
\end{itemize}

\section{Utilities on Lists and Sets}
\begin{itemize}
\item \texttt{permutation($List$,$P$)}\index{\texttt{permutation/2}}: This predicate generates a permutation $P$ of $List$. This predicate is non-deterministic. On backtracking, it generates the next permutation.
\item \texttt{permutations($List$) = $Ps$}\index{\texttt{permutations/1}}: This function returns all the permutations of $List$.
\item \texttt{nextto($E1$,$E2$,$List$)}\index{\texttt{nextto/3}}: This predicate is true if \texttt{$E2$} follows \texttt{$E1$} in \texttt{$List$}. This predicate is non-deterministic.
\end{itemize}

\ignore{
\end{document}
}
