libzahl

get-started.tex (6604B)

---

 \chapter{Get started}
 \label{chap:Get started}
 
 In this chapter, you will learn the basics of libzahl.
 You should read the sections in order.
 
 \vspace{1cm}
 \minitoc
 
 
 % TODO add a section a linking and stuff here.
 
 
 \newpage
 \section{Initialisation}
 \label{sec:Initialisation}
 
 Before using libzahl, it must be initialised. When
 initialising, you must select a location whither libzahl
 long jumps on error.
 
 \begin{alltt}
    #include <zahl.h>
 
    int
    main(void)
    \{
        jmp_buf jmpenv;
        if (setjmp(jmpenv))
            return 1; \textcolor{c}{/* \textrm{Exit on error} */}
        zsetup(jmpenv);
        \textcolor{c}{/* \textrm{\ldots} */}
        return 0;
    \}
 \end{alltt}
 
 {\tt zsetup} also initialises temporary variables used
 by libzahl's functions, and constants used by libzahl's
 functions. Furthermore, it initialises the memory pool
 and a stack which libzahl uses to keep track of temporary
 allocations that need to be pooled for use if a function
 fails.
 
 It is recommended to also uninitialise libzahl when you
 are done using it, for example before the program exits.
 
 \begin{alltt}
    \textcolor{c}{int
    main(void)
    \{
        jmp_buf jmpenv;
        if (setjmp(jmpenv))
            return 1; /* \textrm{Exit on error} */
        zsetup(jmpenv);
        /* \textrm{\ldots} */}
        zunsetup();
        \textcolor{c}{return 0;
    \}}
 \end{alltt}
 
 {\tt zunsetup} frees all memory that has been reclaimed to
 the memory pool, and all memory allocated by {\tt zsetup}.
 Note that this does not free integers that are still
 in use. It is possible to simply call {\tt zunsetup}
 directly followed by {\tt zsetup} to free all pooled
 memory.
 
 
 \newpage
 \section{Exceptional conditions}
 \label{sec:Exceptional conditions}
 
 Exceptional conditions, casually called `errors',
 are treated in libzahl using long jumps.
 
 \begin{alltt}
    int
    main(int argc, char *argv[])
    \{
        jmp_buf jmpenv;
        if (setjmp(jmpenv))
            return 1; \textcolor{c}{/* \textrm{Exit on error} */}
        zsetup(jmpenv);
        return 0;
    \}
 \end{alltt}
 
 Just exiting on error is not a particularly good
 idea. Instead, you may want to print an error message.
 This is done with {\tt zperror}.
 
 \begin{alltt}
    if (setjmp(jmpenv)) \{
        zperror(\textcolor{c}{*argv});
        \textcolor{c}{return 1;}
    \}
 \end{alltt}
 
 \noindent
 {\tt zperror} works just like {\tt perror}. It
 outputs an error description to standard error.
 A line break is printed at the end of the message.
 If the argument passed to {\tt zperror} is neither
 {\tt NULL} nor an empty string, it is printed in
 front of the description, with a colon and a
 space separating the passed string and the description.
 For example, {\tt zperror("my-app")} may output
 
 \begin{verbatim}
    my-app: Cannot allocate memory
 \end{verbatim}
 
 libzahl also provides {\tt zerror}. Calling this
 function will provide you with an error code and
 a textual description.
 
 \begin{alltt}
    \textcolor{c}{if (setjmp(jmpenv)) \{}
        const char *description;
        zerror(&description);
        fprintf(stderr, "\%s: \%s\verb|\|n", *argv, description);
        \textcolor{c}{return 1;}
    \textcolor{c}{\}}
 \end{alltt}
 
 \noindent
 This code behaves like the example above that
 calls {\tt zperror}. If you are interested in the
 error code, you instead look at the return value.
 
 \begin{alltt}
    \textcolor{c}{if (setjmp(jmpenv)) \{}
        enum zerror e = zerror(NULL);
        switch (e) \{
        case ZERROR_ERRNO_SET:
            perror("");
            \textcolor{c}{return 1;}
        case ZERROR_0_POW_0:
            fprintf(stderr, "Indeterminate form: 0^0\verb|\|n");
            \textcolor{c}{return 1;}
        case ZERROR_0_DIV_0:
            fprintf(stderr, "Indeterminate form: 0/0\verb|\|n");
            \textcolor{c}{return 1;}
        case ZERROR_DIV_0:
            fprintf(stderr, "Do not divide by zero, dummy\verb|\|n");
            \textcolor{c}{return 1;}
        case ZERROR_NEGATIVE:
            fprintf(stderr, "Undefined (negative input)\verb|\|n");
            \textcolor{c}{return 1;}
        case ZERROR_INVALID_RADIX:
            fprintf(stderr, "Radix must be at least 2\verb|\|n");
            \textcolor{c}{return 1;}
        default:
            zperror("");
            \textcolor{c}{return 1;}
        \}
    \textcolor{c}{\}}
 \end{alltt}
 
 To change the point whither libzahl's functions
 jump, call {\tt setjmp} and {\tt zsetup} again.
 
 \begin{alltt}
    jmp_buf jmpenv;
    if (setjmp(jmpenv)) \{
        \textcolor{c}{/* \textrm{\ldots} */}
    \}
    zsetup(jmpenv);
    \textcolor{c}{/* \textrm{\ldots} */}
    if (setjmp(jmpenv)) \{
        \textcolor{c}{/* \textrm{\ldots} */}
    \}
    zsetup(jmpenv);
 \end{alltt}
 
 
 \newpage
 \section{Create an integer}
 \label{sec:Create an integer}
 
 To do any real work with libzahl, we need integers. The
 data type for a big integer in libzahl is {\tt z\_t}
 \psecref{sec:Integer structure}. Before a {\tt z\_t}
 can be assigned a value, it must be initialised.
 
 \begin{alltt}
    z_t a;
    \textcolor{c}{/* \textrm{\ldots} */
    zsetup(jmpenv);}
    zinit(a);
    \textcolor{c}{/* \textrm{\ldots} */
    zunsetup();}
 \end{alltt}
 
 \noindent
 {\tt zinit(a)} is actually a less cumbersome and optimised
 alternative to calling {\tt memset(a, 0, sizeof(z\_t))}.
 It sets the values of two members: {\tt .alloced} and
 {\tt .chars}, to 0 and {\tt NULL}. This is necessary,
 otherwise the memory allocated could be fooled to deallocate
 a false pointer, causing the program to abort.
 
 Once the reference has been initialised, you may assign it
 a value. The simplest way to do this is by calling
 
 \begin{alltt}
    void zseti(z_t a, int64_t value);
 \end{alltt}
 
 \noindent
 For example {\tt zseti(a, 1)}, assignes the value 1 to
 the {\tt z\_t} {\tt a}.
 
 When you are done using a big integer reference, you should
 call {\tt zfree} to let libzahl know that it should pool
 the allocation of the {\tt .chars} member.
 
 \begin{alltt}
    z_t a;
    zinit(a);
    \textcolor{c}{/* \textrm{\ldots} */}
    zfree(a); \textcolor{c}{/* \textrm{before \texttt{zunsetup}} */}
 \end{alltt}
 
 \noindent
 Instead of calling {\tt zfree(a)}, it is possible — but
 strongly discouraged — to call {\tt free(a->chars)}.
 Note however, by doing so, the allocation is not pooled
 for reuse.
 
 If you plan to reuse the variable later, you need to
 reinitialise it by calling {\tt zinit} again.
 
 Alternatives to {\tt zseti} include \psecref{sec:Assignment}:
 
 \begin{alltt}
    void zsetu(z_t a, uint64_t value);
    void zsets(z_t a, const char *value);
    void zset(z_t a, z_t value); \textcolor{c}{/* \textrm{copy \texttt{value} into \texttt{a}} */}
 \end{alltt}