\documentclass[noanswers,addpoints,11pt]{exam}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[most]{tcolorbox}
\usepackage{datetime}
\usepackage{enumerate}
\usepackage{xltxtra}
\usepackage{listings}

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

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

\lstset{
  basicstyle=\ttfamily,
  language=java,
}

\newcommand{\checkpoint}{{\Large $\checkmark$} }

% classname
\newcommand\assignmentTitle{Converting Number Bases in Java}
\newcommand\semester{Spring 2024}
\newcommand\className{Assembly and Computer Architecture}
\newcommand\classNumber{CIS~356}
\newcommand\classFullName{\classNumber~\className}
\renewcommand{\dateseparator}{-}
\yyyymmdddate

% /classname

\pagestyle{headandfoot}
\firstpageheader{\classNumber\\\semester}{\assignmentTitle\\~}{\today\\~}
\runningheader{\assignmentTitle}{}{\today}

\newenvironment{showExample}[1]{
  \begingroup
  \renewcommand{\solutiontitle}{\noindent\textbf{Example:}\enspace}
  \printanswers
  \begin{solution}[#1]
  }{
  \end{solution}
  \endgroup
}

\definecolor{outputgray}{gray}{0.95}


\begin{document}
\pointsinrightmargin{}

\section*{Learning Outcomes}
Upon completing this assignment, students should be able to

\begin{itemize}
\item Use the \emph{repeated division} method to convert a Java
  \lstinline{int} into a \lstinline{String} representation in
  \emph{binary}, \emph{decimal}, or \emph{hexadecimal}.
  \item Test and document the code.
\end{itemize}

\section*{Introduction}
Converting between number bases is a skill that is necessary when
working at a low-level in a computer. Tools will display memory and
register values in hex, decimal, or binary and one must be comfortable
with converting these to a common base to be able to check the
correctness of a circuit.

One way to learn how to do this is to practice rote translation across
one or two hundred problems. An alternative, that is designed to get
the \emph{algorithm} to stick, is to implement a program, in a
language that you know, that does it. Designing, programming, testing,
and debugging such a program will make a lasting impression in your
mind. Using Java, a programming language you are comfortable with,
makes it easier to focus on the base conversion rather than the
implementation details.

This also turns out to be a really good place to start discussing how
the \lstinline{Integer.decode} (and \lstinline{Integer.parseInt})
method works.

\section*{Method}
\subsection*{Getting Started}

You are to write a Java program that
\begin{enumerate}
\item Reads its command-line for arguments
\item Handles commands to generate output in binary, decimal, and/or
  hex.
\item Handles an arbitrary number of string representations of
  integers as input values (decimal or hex).
\item Handles a command to show its work.
\end{enumerate}


\subsubsection*{\texttt{main}: construct and \texttt{run}}
The program design is constrained in that it \textbf{must} make good
use of methods and \textbf{must not} have any \lstinline{static}
methods other than \lstinline{main}.

An easy way to handle this is to construct an object in
\lstinline{main} (of the application class type) and then call a
\lstinline{run} method on it to do the real work. An example
\lstinline{Hello} program is below:

\newpage
\begin{lstlisting}[language=java]
public class Hello {
  private static final String DEFAULT_NAME = "World";
  private String toWhom;

  public Hello(String whom) {
    toWhom = whom;
  }

  public void run() {
    System.out.printf("Hello, %s!\n", toWhom);
  }

  public static void main(String[] args) {
    String whoToSayHelloTo = DEFAULT_NAME;
    if (args.length > 0)
      whoToSayHelloTo = args[0];

    Hello applicationObject = new Hello(whoToSayHelloTo);
    applicationObject.run();
  }
}
\end{lstlisting}

The key is to note the constructor and the \lstinline{run} method and
then the last two lines of \lstinline{main}: a \lstinline{Hello}
object is constructed with the provided command-line arguments \emph{or}
default values. Then that object is \lstinline{run} to do the body of
the program.

Your program will have more complex argument processing, more
constructor parameters, and (hopefully) many more small, single
purpose functions to help \lstinline{run}.

\section*{Input/Output}
\subsection*{Command-line Parameters}
The program takes any number of command-line parameters. An argument
string starting with \texttt{--} is a command to the program to change
its behavior; any other argument is expected to be a string containing
an integer, either decimal, \lstinline{2564}, or hexadecimal,
\lstinline{0x12345}.

There are four recognized commands (any other \texttt{--} command
should generate a warning message and be ignored).

\noindent
\textbf{\texttt{--dec}} Display the \emph{decimal} translation of the integers.

\noindent
\textbf{\texttt{--hex}} Display the \emph{hexadecimal} translation of
the integers.

\noindent
\textbf{\texttt{--bin}} Display the \emph{binary} translation of the integers.

\noindent
\textbf{\texttt{--verbose}} Show the repeated divisions used to
generate each translation before showing the translation.

The program should \emph{require} at least one integer to convert.

\newpage
\subsection*{Example Runs}

\begin{lstlisting}[language={},backgroundcolor=\color{outputgray}]
$ java NumberBases --bin 100
  0b110 0100

$ java NumberBases --hex --verbose 25 0x100
  16 |   25
     |    1  9
     |    0  1
  0x19

  16 |  256
     |   16  0
     |    1  0
     |    0  1
  0x100

$ java NumberBases --dec --verbose 185
  10 |   185
     |    18  5
     |     1  8
     |     0  1
  185

$ java NumberBases 0x40
  64
\end{lstlisting}

\section*{Testing}
Test program by checking known values. Check edge conditions.

Valid range for unsigned, decimal integers is 0 --  2147483647 $2^{31}
- 1$

\section*{Documentation}

\subsubsection*{\lstinline{README}}
Must document how you tested. How do you know that it is right?

Must include instructions on how to \textbf{compile} and how to
\textbf{run} the program as submitted. You can test these if you
\lstinline{clone} the repository you submitted into a \textbf{brand
  new location}. You can then follow the instructions and see if all
the necessary files are in the repo.

\subsection*{Deliverables}
\textbf{Submission medium}: \lstinline{git} to Gitea at
\lstinline{cs-devel.potsdam.edu}. The repo name is
\lstinline{p001-NumberBases} and it goes in your organization for
turning in assignments in CIS 356 this semester.
\end{document}

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