.\" 
.\" 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: geoLnArr.3,v 1.6 2004/09/22 21:57:50 tkgeomap Exp $
.so man.macros
.TH geoLnArr 3 2 Geography "Geography C functions"
.SH NAME
GeoLnArr, GeoLnArrCreate, GeoLnArrSetDescr, GeoLnArrSetAlloc, GeoLnArrAddLine, GeoLnArrPutLine, GeoLnArrContainGeoPt, GeoLnArrGetDescr, GeoLnArrGetInfo, GeoLnArrGetLine, GeoLnArrFree, GeoLnArrDestroy, \- manage GeoLnArr objects, which are containers for GeoLn objects.
.SH SYNOPSIS
.nf
\fB#include <geoLines.h>\fR
\fBGeoLnArr GeoLnArrCreate(unsigned \fInLinesMax\fB);\fR
\fBvoid GeoLnArrSetAlloc(GeoLnArr \fIgeoLnArr\fB, unsigned \fInLinesMax\fB);\fR
\fBvoid GeoLnArrFree(GeoLnArr \fIgeoLnArr\fB);\fR
\fBvoid GeoLnArrDestroy(GeoLnArr \fIgeoLnArr\fB);\fR
\fBvoid GeoLnArrSetDescr(GeoLnArr \fIgeoLnArr\fB, CONST char *\fIdescr\fB);\fR
\fBint GeoLnArrAddLine(GeoLn \fIgeoLn\fB, GeoLnArr \fIgeoLnArr\fB);\fR
\fBint GeoLnArrPutLine(GeoLn \fIgeoLn\fB, GeoLnArr \fIgeoLnArr\fB);\fR
\fBint GeoLnArrContainGeoPt(GeoPt \fIgeoPt\fB, GeoLnArr \fIgeoLnArr\fB);\fR
\fBchar *GeoLnArrGetDescr(GeoLnArr \fIgeoLnArr\fB);\fR
\fBstruct GeoLnArrInfo GeoLnArrGetInfo(GeoLnArr \fIlnArr\fB);\fR
\fBGeoLn GeoLnArrGetLine(GeoLnArr \fIgeoLnArr\fB, unsigned \fIn\fB);\fR
.fi
.SH DESCRIPTION
These functions create, manipulate, and access geolinearrays, which are arrays
of geolines.  Geolines are arrays of geographic points.  See
geoLn(3) and geography(3) for information on geolines and geographic points.
Geolinearrays are represented as objects of type \fBGeoLnArr\fR.
.PP
\fBGeoLnArrCreate\fR creates and initializes a geolinearray with storage for
up to \fInLinesMax\fR geolines.  It returns a new geolinearray, or \fBNULL\fR
if it fails.  When no longer needed, the array should be destroyed
with a call to \fBGeoLnArrDestroy\fR.
.PP
\fBGeoLnArrSetAlloc\fR sets the internal allocation for \fIgeoLnArr\fR so that
it can hold up to \fInLinesMax\fR geolines.
.PP
\fBGeoLnArrFree\fR frees internal storage in \fIgeoLnArr\fR.
.PP
\fBGeoLnArrDestroy\fR frees internal storage in \fIgeoLnArr\fR and frees
\fIgeoLnArr\fR.
.PP
\fBGeoLnArrSetDescr\fR sets the descriptor for \fIgeoLnArr\fR to \fIdescr\fR.
The descriptor is a text string with no required format which normally contains
human-readable information about the geolinearray.
.PP
\fBGeoLnArrGetDescr\fR returns the descriptor for \fIgeoLnArr\fR.  The return 
value should not be modified by the caller.
.PP
\fBGeoLnArrAddLine\fR copies \fIgeoLn\fR onto the end of \fIgeoLnArr\fR.  It 
automatically increases \fIgeoLnArr\fR's allocation if necessary.
\fBGeoLnArrAddLine\fR returns true if successful, otherwise it returns false,
leaving \fIgeoLnArr\fR untouched.
.PP
\fBGeoLnArrPutLine\fR behaves similarly to \fBGeoLnArrAddLine\fR, except that
it transfers \fIgeoLn\fR onto the end of \fIgeoLnArr\fR, instead of making a
copy.  \fIgeoLn\fR becomes the property of \fIgeoLnArr\fR.  The user should not
subsequently modify or delete \fIgeoLn\fR.  \fBGeoLnArrPutLine\fR is
faster and more efficient with memory and \fBGeoLnArrAddLine\fR.
\fBGeoLnArrPutLine\fR returns true if successful, otherwise it returns false,
leaving \fIgeoLnArr\fR untouched.
.PP
\fBGeoLnArrContainGeoPt\fR returns true if any geoline in \fIgeoLnArr\fR
contains \fIgeoPt\fR, as determined by \fBGeoLnContainPt\fR (see geoLn(3)).
.PP
\fBGeoLnArrGetInfo\fR returns a structure of form:
.CS
struct GeoLnArrInfo {
    unsigned	nLines;		/* Number of lines */
    unsigned	nPts;		/* Number of points for all lines */
    unsigned	nMax;		/* Number of points in longest line */
    Angle	latMax;		/* Max longitude for all lines */
    Angle	lonMax;		/* Max latitude for all lines */
    Angle	latMin;		/* Min longitude for all lines */
    Angle	lonMin;		/* Min latitude for all lines */
};
.CE
in which \fBnLines\fR is the number of lines in \fIgeoLnArr\fR,
\fBnPts\fR is the number of points for all lines,
\fBnMax\fR is the number of points in longest line,
\fBlatMax\fR is the maximum longitude for all lines in Angle units,
\fBlonMax\fR is the maximum latitude for all lines in Angle units,
\fBlatMin\fR is the minimum longitude for all lines in Angle units,
and \fBlonMin\fR is the minimum latitude for all lines in Angle units.
See the \fBgeography\fR (3) man page for information on Angle units.
.PP
\fBGeoLnArrGetLine\fR returns the geoline with index \fIn\fR from
\fIgeoLnArr\fR.  The first geoline in a geolinearray has index \fB0\fR.
It returns \fBNULL\fR if \fIn\fR is out of bounds.
.SH "SEE ALSO"
geoLn, geography
.SH KEYWORDS
GeoLnArr, geolinearray, geography, container
.SH AUTHOR
Gordon Carrie (user0@tkgeomap.org)