Arrays

Array objects consist of lists of other objects, each of which can potentially be of a different type. Accordingly, we have a function to enquire how long a list we have:


\begin{lstlisting}
int pdf_array_len(fz_context *ctx, pdf_obj *array);
\end{lstlisting}

Armed with this knowledge we can then fetch any object we want from within the array.


\begin{lstlisting}
pdf_obj *pdf_array_get(fz_context *ctx, pdf_obj *array, int i);
\end{lstlisting}

Ideally i should be between 0 and length-1 (though the function will just return NULL if an out of range element is requested).

Note that the pdf_obj reference returned by this function is merely borrowed. That is to say, if you wish to keep the object pointer around for more than the immediate lifespan of the call, you should manually call pdf_keep_obj to keep it, and later pdf_drop_obj to dispose of it.

An object can be inserted into an array at a given index, using:


\begin{lstlisting}
void pdf_array_insert(fz_context *ctx, pdf_obj *array, pdf_obj *obj, int index);
\end{lstlisting}

Any objects after this point are shuffled up the array. Alternatively an object can be put into an array at a given point, overwriting any object that is there already:


\begin{lstlisting}
void pdf_array_put(fz_context *ctx, pdf_obj *array, int i, pdf_obj *obj);
\end{lstlisting}

If the array needs to be extended it will be, and any intervening objects will be created as `null'. Alternatively objects can be appended to an array using:


\begin{lstlisting}
void pdf_array_push(fz_context *ctx, pdf_obj *array, pdf_obj *obj);
\end{lstlisting}

In all these cases, the array will take new references to the object passed in - that is, after the call, both the array and the caller will hold references to the object. In cases where the object to be inserted is a `borrowed' reference, this is ideal.

In other cases, where the ownership of the object reference should be passed down into the array, we have alternative formulations of those functions:


\begin{lstlisting}
void pdf_array_insert_drop(fz_context *ctx, pdf_obj *array, p...
...array_push_drop(fz_context *ctx, pdf_obj *array, pdf_obj *obj);
\end{lstlisting}

These functions are so named because they are equivalent to first inserting/putting/pushing the object, and then dropping it, with the nice side effect that any errors encountered during the push still result in the object being correctly dropped, often saving the caller from having to wrap the call in a fz_try/fz_catch clause.