\documentclass[answers,addpoints,10pt]{exam}
\usepackage[utf8]{inputenc}

\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{hyperref}

\usepackage{datetime}

\usepackage{enumerate}
\usepackage{enumitem}

\usepackage{xltxtra}
\usepackage{listings}
\usepackage{listings-mips}

\usepackage{graphicx}
\usepackage{makecell}
\usepackage{multicol}
\usepackage{multirow}

\usepackage{tabularx}
\usepackage{textcomp}
\usepackage{tikz}
\usetikzlibrary{arrows,automata,decorations.pathmorphing,backgrounds,positioning,fit}

\usepackage{fontspec}
\setmainfont{Gentium Book Basic}
\setmonofont{Comic Code}[
  Scale          = 0.85,
]

\lstset{
  basicstyle=\ttfamily,
  language=[mips]assembler,
  numbers=left,
  numberstyle=\footnotesize
}

\DeclareMathOperator{\limplies}{\Rightarrow}
\DeclareMathOperator{\liff}{{\Leftrightarrow}}
\DeclareMathOperator{\lxor}{\oplus}
\DeclareMathOperator{\qeq}{\overset{?}{=}}
\DeclareMathOperator{\modulus}{\mathbf{mod}}
\DeclareMathOperator{\even}{even}
\DeclareMathOperator{\odd}{odd}
\DeclareMathOperator{\ddiv}{|}
\DeclareMathOperator{\ndiv}{\not|}
\DeclareMathOperator{\contra}{\Rightarrow\mskip-\thinmuskip\Leftarrow}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\Z}{\mathbb{Z}}
\renewcommand{\P}[1]{\mathbb{P}(#1)}
\newcommand{\mathcheckmark}{\text{ \ding{51}}}

\DeclareMathOperator{\vowel}{vowel}
\DeclareMathOperator{\consonant}{consonant}
\DeclareMathOperator{\isprime}{prime}
\DeclareMathOperator{\equals}{equals}
\DeclareMathOperator{\divides}{divides}

\newcommand\examNumber{pStrings -- String Library Functions}
\newcommand\semester{Spring 2024}
\newcommand\className{Assembly}
\newcommand\classNumber{CIS~356}
\newcommand\classFullName{\classNumber~\className}
\renewcommand{\dateseparator}{-}
\yyyymmdddate

% /classname
\pagestyle{plain}

\begin{document}

\section*{Learning Outcomes}
After completing this program, students will be able to
\begin{itemize}
\item \textbf{Write} a \emph{library} of functions in a separate
  assembly file.
\item \textbf{Manipulate} C-style strings (character arrays).
\end{itemize}

\noindent
\textbf{Note:} For \emph{this} assignment you may make use of the
\lstinline{mult} instruction it MIPS.

\section*{Overview}
Students will write a program that prompts the user for a \emph{line}
of text until the user enters \lstinline{"done"}. Each line will be
broken up into ``words'' on \emph{space} characters with each word
printed on a separate line.

Think for a minute: how would you write this program in Java using the
\lstinline{length}, \lstinline{indexOf}, \lstinline{substring} and
assignment to another string, \lstinline{word}. The input string is
split into parts separated by single space characters until the line
is empty.

\newcounter{rememberQuestion}{0}
\section*{Procedure}
\begin{questions}
\question{} Read this entire assignment. Spend a few minutes thinking
  about what you are going to do.
  \setcounter{rememberQuestion}{\value{question}}
\end{questions}

\subsection*{String Library}
\begin{questions}
  \setcounter{question}{\value{rememberQuestion}}
\question{} You will write (at least) two assembly files. One,
  \lstinline{main.s}, will contain the \lstinline{main} method along
  with the \lstinline{.data} segment and program specific functions.

  The other file, \lstinline{string.s}, contains all of the standard
  routines in the string library. Your library must include \emph{all}
  of the following \textbf{global} functions; the global functions
  must adhere, \textbf{exactly}, to the given interfaces. If you
  discover a better signature or interface for a function you must
  give it a \emph{different} name and then \emph{implement} the global
  functions using your great new function.

  \textbf{Terminology:} a \emph{buffer} and a \emph{string} are both
  passed as the address of (pointer at) a character array
  (\lstinline{char *}).  A \emph{string} is always
  \lstinline{NUL}-terminated (ends with \lstinline{'\0'}); a
  \emph{buffer} is not, necessarily, \lstinline{NUL}-terminated and
  can be space set aside to hold a new string.

  \begin{description}[style=nextline]
  \item[\texttt{char * chomp(char * str)}]
    \lstinline{str} -- a \emph{non-null} \textbf{string}\\
    ``Chomps'' off all \emph{trailing} tabs, carriage returns, line
    feeds, and the like. This is done by trimming \emph{all}
    characters with ASCII codes less than 32 (the space character,
    \lstinline{' '}, is ASCII 32). Trimming is halted when the string
    is \emph{empty} or a character at or above code 32 is encountered.\\
    Returns \lstinline{str}.

    \item[\texttt{int strlen(char * str)}]
      \lstinline{str} -- a \emph{non-null} \textbf{string}\\
      Counts the number of characters (bytes) before the
      \lstinline{NUL}.\\
      Returns the \emph{length} of \lstinline{str}.

  \item[\texttt{char * strcpy(char * destination, char * source)}]
    \lstinline{destination} -- a \emph{non-null} \textbf{buffer}\\
    \lstinline{source} -- a \emph{non-null} \textbf{string}\\
    Copies the string \lstinline{source} into the memory pointed to by
    \lstinline{destination}, including the \lstinline{NUL}.\\
    Returns \lstinline{destination}.

  \item[\texttt{char * strcat(char * destination, char * source)}]
    \lstinline{destination} -- a \emph{non-null} \textbf{string}\\
    \lstinline{source} -- a \emph{non-null} \textbf{string}\\
    Copies the string \lstinline{source} onto the end of the string
    \lstinline{destination}, including the \lstinline{NUL}.\\
    Returns \lstinline{destination}.

  \item[\texttt{char * strncpy(char * destination, char * source, int
        n)}]
    \lstinline{destination} -- a \emph{non-null} \textbf{buffer}\\
    \lstinline{source} -- a \emph{non-null} \textbf{string}\\
    \lstinline{n} -- the \emph{maximum} number of characters to copy\\
    Copies the string \lstinline{source} into the memory pointed to by
    \lstinline{destination}, including the \lstinline{NUL} if
    \lstinline{strlen(source)} is less than \lstinline{n} and just
    \lstinline{n} characters otherwise (\emph{Correct:} might
    \textbf{not} copy in a \lstinline{NUL}).\\
    Returns \lstinline{destination}.

  \item[\texttt{char * strncat(char * destination, char * source, int
        n)}]
    \lstinline{destination} -- a \emph{non-null} \textbf{string}\\
    \lstinline{source} -- a \emph{non-null} \textbf{string}\\
    \lstinline{n} -- the \emph{maximum} number of characters to copy\\
    Copies the string \lstinline{source} onto the end of
    \lstinline{destination}, including the \lstinline{NUL} if
    \lstinline{strlen(source)} is less than \lstinline{n} and just
    \lstinline{n} characters otherwise (\emph{Correct:} might
    \textbf{not} copy in a \lstinline{NUL}).\\
    Returns \lstinline{destination}.

  \item[\texttt{int strcmp(char * left, char * right)}]
    \lstinline{left} -- a \emph{non-null} \textbf{string}\\
    \lstinline{right} -- a \emph{non-null} \textbf{string}\\
    Compare \lstinline{left} to \lstinline{right}, character by
    character returning an int reflecting the relationship between
    them.\\
    Returns \textbf{negative} value if \lstinline{left} <
    \lstinline{right} (lexicagraphically), \textbf{zero} if they are
    the same, and a \textbf{positive} value if \lstinline{left} >
    \lstinline{right}.

  \item[\texttt{char * strchar(char * str, char ch)}]
    \lstinline{str} -- a \emph{non-null} \textbf{string}\\
    \lstinline{ch} -- a character to search for\\
    Scan across \lstinline{str} for a match for \lstinline{ch}.\\
    Returns address of first occurrence of \lstinline{ch} in
    \lstinline{str} or, if none is found, the \lstinline{NULL}
    pointer.\\(\textbf{\lstinline{NULL}} != \textbf{\lstinline{NUL}})

  \item[{\texttt{char * substring(char * destination, char * source, int
        start, int n)}}]
    \lstinline{destination} -- a \emph{non-null} \textbf{buffer}\\
    \lstinline{source} -- a \emph{non-null} \textbf{string}\\
    \lstinline{start} -- the \emph{offset} in \lstinline{source} from
    which to start copying\\
    \lstinline{n} -- the \emph{maximum} number of characters to copy\\
    Copies the string from \lstinline{source[start]} to
    \lstinline{destination} until \lstinline{n} characters or the end
    of \lstinline{source} is reached. If \lstinline{start} is out of
    bounds, copy zero characters. If fewer than \lstinline{n} bytes
    were copied, append a \lstinline{NUL}.\\
    Returns \lstinline{destination}.
\end{description}
\question{} The \textbf{main} program that uses the string library
  follows a really simple CS I program: loop, prompting the user for a
  \emph{line} of text and breaking the line into individual words,
  printing one word per line, until the input is the sentinel value.

  In a C/Java-like syntax:
\begin{lstlisting}[language=java]
while (true) {
  char *  line = promptReadAndChomp("Next line: ", line, 100);
  char * word;

  if (strcmp(line, "done") == 0)
    break;

  char * space; // location of leftmost ' ' in line
  while ((space = strchr(line, ' ')) != NULL) {
    word = substring(word, line, 0, space - line);
    line = substring(line, line, (space - line) + 1, 100);
    println(word);
  }
  if (strlen(line) > 0)
    println(line); // whatever is leftover
}
\end{lstlisting}



\setcounter{rememberQuestion}{\value{question}}
\end{questions}

\subsection*{Testing}
\begin{questions}
  \setcounter{question}{\value{rememberQuestion}}

\question{} You should build small test programs for each
  routine in the string library. To have MARS do the right thing:
  \begin{itemize}
  \item Start with your test program, \lstinline{testChomp.s} in the
    same folder as \lstinline{strlib.s}. Write a program that, say,
    reads a line and chomps the end off of it.
  \item Test the library routine by assembling the test program and
    giving it some input (or build data in RAM if that makes more
    sense to you). (Make sure, with \lstinline{chomp} in particular,
    to have more than just \lstinline{\n} at the end of the string;
    remember that \lstinline{\t} should get chomped, too.)
  \item After you are happy that the test passes, make a sibling
    directory for your main, \lstinline{strlib.s}, directory. Maybe
    call it \lstinline{testChomp}. Move \lstinline{testChomp.s} to
    that folder so that you can put a different \lstinline{main} file
    in with the library.
  \item \textbf{Notice} this is a great time to check the working code
    into \lstinline{git}, too.
  \item If, in the future, you seem to have problems with
    \lstinline{chomp}, you could copy the current state of
    \lstinline{strlib.s} into \lstinline{testChomp/} and run
    \lstinline{testChomp.s} against the newest library.

    Don't forget to backport changes in \lstinline{testChomp/strlib.s}
    to the main copy. When done with this testing, you should make
    sure the backporting is done and \emph{delete} the copy of the
    library. Really. Use the \textbf{DRY} Principle --- \textbf{D}o
    not \textbf{R}epeat \textbf{Y}ourself: have a \emph{canonical}
    place for everything and \emph{only} keep it there.
  \end{itemize}

  This test pattern is not part of the grading rubric (would probably
  garner \emph{Aesthetic} points). Your code should work, be clean,
  and be well documented. Building working components is a good way to
  get to working code.

\end{questions}

\section*{Submit through Gitea}
\paragraph{Check your working code into \lstinline{git}.} When you have
one working ``feature'' in your program, checking it in to
\lstinline{git} is a \emph{good thing}. Protect yourself from
making things \emph{worse}.

Use a \lstinline{.gitignore} file to exclude any garbage files your
IDE produces from the repository. They will cost you points.

You have an account on the departmental \textbf{Gitea} server. Submit
your work in your shared organization in a repo named
\lstinline{pAddingSomeNumbers}



\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
