.\"
.\" 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: mapLn.3,v 1.7 2004/09/22 21:57:50 tkgeomap Exp $
.so man.macros
.TH mapLn 3 2 Geography "Geography C functions"
.SH NAME
MapLn, MapLnCreate, MapLnClear, MapLnSetAlloc, MapLnAddPt, MapLnGetPt, MapLnDestroy \- container for map points.
.SH SYNOPSIS
.nf
\fB#include <mapLines.h>\fR
\fBMapLn MapLnCreate(unsigned \fInptsMax\fB);\fR
\fBvoid MapLnSetAlloc(MapLn \fImapLn\fB, unsigned \fInptsMax\fB);\fR
\fBvoid MapLnClear(MapLn \fImapLn\fB);\fR
\fBvoid MapLnDestroy(MapLn \fImapLn\fB);\fR
\fBvoid MapLnAddPt(MapPt \fImapPt\fB, MapLn \fImapLn\fB);\fR
\fBMapPt MapLnGetPt(MapLn \fImapLn\fB, unsigned \fIn\fB);\fR
.fi
.SH DESCRIPTION
These functions create, manipulate and access maplines, which are arrays
of map points.  See \fBgeography\fR (3) for information on map points.
Maplines are represented by objects of type \fBMapLn\fR.
.PP
\fBMapLnCreate\fR creates and initializes a mapline with enough memory allocated
to store \fInptsMax\fR map points.  It returns the new mapline, or NULL if
it fails.  When no longer needed, the mapline should be destroyed with a call
to \fBMapLnDestroy\fR.
.PP
\fBMapLnSetAlloc\fR sets the allocation of \fImapLn\fR to \fInptsMax\fR.
.PP
\fBMapLnClear\fR removes all points from \fImapLn\fR, but does not free it's
storage.  This reduces memory management overhead for maplines that are reused.
.PP
\fBMapLnDestroy\fR frees all storage associated with \fImapLn\fR.
.PP
\fBMapLnAddPt\fR adds \fImapPt\fR to the end of \fImapLn\fR.  It increases
\fImapLn\fR's allocation automatically, if necessary.
.PP
\fBMapLnGetPt\fR returns the map point at offset \fIn\fR from
\fImapLn\fR.  The first point in the line has offset \fB0\fR.
\fBMapLnGetPt\fR returns \fBMapPtNowhere()\fR if \fIn\fR is out of bounds.
.SH "SEE ALSO"
mapLnArr, mapLn, mapLnArr, geography
.SH KEYWORDS
MapLn, mapline, geography, container
.SH AUTHOR
Gordon Carrie (user0@tkgeomap.org)