.\"
.\" Copyright (c) 2004 Gordon D. Carrie.  All rights reserved.
.\" 
.\" Licensed under the Open Software License version 2.1
.\" 
.\" Please address questions and feedback to user0@tkgeomap.org
.\" 
.\" @(#) $Id: mapLnArr.3,v 1.7 2004/09/22 21:57:50 tkgeomap Exp $
.so man.macros
.TH mapLnArr 3 2 Geography "Geography C functions"
.SH NAME
MapLnArr, MapLnArrCreate, MapLnArrSet, MapLnArrSetDescr, MapLnArrSetAlloc, MapLnArrAddLine, MapLnArrGetDescr, MapLnArrGetLine, MapLnArrDestroy \- container for MapLn objects.
.SH SYNOPSIS
.nf
\fB#include <mapLines.h>\fR
\fBMapLnArr MapLnArrCreate(unsigned \fInLinesMax\fB);\fR
\fBvoid MapLnArrSetAlloc(MapLnArr \fImapLnArr\fB, unsigned \fInLinesMax\fB);\fR
\fBvoid MapLnArrDestroy(MapLnArr \fImapLnArr\fB);\fR
\fBvoid MapLnArrSet(MapLnArr \fImapLnArr\fB, GeoLnArr \fIgeoLnArr\fB, GeoProj \fIproj\fB, Rotation \fIrxn\fB);\fR
\fBvoid MapLnArrSetDescr(MapLnArr \fImapLnArr\fB, CONST char *\fIdescr\fB);\fR
\fBchar *MapLnArrGetDescr(MapLnArr \fImapLnArr\fB);\fR
\fBvoid MapLnArrAddLine(MapLn \fImapLn\fB, MapLnArr \fImapLnArr\fB);\fR
\fBvoid MapLnArrPutLine(MapLn \fImapLn\fB, MapLnArr \fImapLnArr\fB);\fR
\fBMapLn MapLnArrGetLine(MapLnArr \fImapLnArr\fB, unsigned \fIn\fB);\fR
.fi
.SH DESCRIPTION
These functions create, manipulate, and access maplinearrays, which are arrays
of maplines.  Maplines are arrays of map points.  See
MapLn(3) and Geography(3) for information on maplines and map points.
Maplinearrays are represented as objects of type \fBMapLnArr\fR.
.PP
\fBMapLnArrCreate\fR creates and initializes a maplinearray with storage for
up to \fInLinesMax\fR maplines.  It returns the new maplinearray, or \fBNULL\fR
if it fails.  When no longer needed, the array should be destroyed with a call
to \fBMapLnArrDestroy\fR.
.PP
\fBMapLnArrSetAlloc\fR sets the internal allocation for \fImapLnArr\fR so that
it can hold up to \fInLinesMax\fR maplines.
.PP
\fBMapLnArrDestroy\fR destroys \fImapLnArr\fR, provided its user count is zero.
Returns true if successful.  Returns false if \fImapLnArr\fR is in use.
.PP
\fBMapLnArrSet\fR stores the geolinearray \fIgeoLnArr\fR, projection
\fIproj\fR, and rotation \fIrxn\fR which presumably produced \fImapLnArr\fR.
.PP
\fBMapLnArrSetDescr\fR sets the descriptor for \fImapLnArr\fR to \fIdescr\fR.
.PP
\fBMapLnArrGetDescr\fR returns the descriptor for \fImapLnArr\fR.  The return 
value should not be modified by the caller.
.PP
\fBMapLnArrAddLine\fR adds a copy of \fImapLn\fR to the end of \fImapLnArr\fR.
It automatically increases \fImapLnArr\fR's allocation if necessary.
.PP
\fBMapLnArrPutLine\fR adds \fImapLn\fR to the end of \fImapLnArr\fR.
It automatically increases \fImapLnArr\fR's allocation if necessary.
\fImapLn\fR becomes the property of \fImapLnArr\fR and should not be
subsequently modified by the user.
.PP
\fBMapLnArrGetLine\fR get the mapline with index \fIn\fR from \fImapLnArr\fR.
The first mapline in a maplinearray has index \fB0\fR.  It returns \fBNULL\fR
if \fIn\fR is out of bounds.
.SH "SEE ALSO"
mapLn, mapLn, mapLnArr, geography
.SH KEYWORDS
MapLnArr, maplinearray, geography, container
.SH AUTHOR
Gordon Carrie (user0@tkgeomap.org)