vectorlib.dox: add examples, minor updates

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@52573 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/vector/vectorlib.dox

@@ -76,7 +76,9 @@ internal file based storage the geometry may alternatively be stored
 in a PostGIS database (accessible via OGR interface). This enables
 users to maintain large data sets with simultaneous write
 access. External GIS formats such as SHAPE-files may be used directly,
-without requiring format conversion.
+without requiring format conversion. All vector data accessed through 
+the OGR interface have only pseudo-topology and only a limited subset 
+of vector operations can be performed.
 
 The current implementation includes:   
 
@@ -103,16 +105,16 @@ consisting of curves called arcs. An arc is stored as a series of
 x,y,z coordinate pairs. The two endpoints of an arc are called
 <em>nodes</em>. Two consecutive x,y,z pairs define an arc segment. The
 user specifies the type of input to GRASS; GRASS doesn't decide. GRASS
-allows for the feature definition which allows for multiple types to
-co-exist in the same map. Centroid are assigned to area it is
-within/inside (geometrically). An area is identified by an x,y,z
-centroid point geometrically inside with a category number. This
-identifies the area. Such centroids are stored in the same binary
+supports feature type definition which allows for multiple types to
+co-exist in the same map. A centroid is assigned to the area it is
+within/inside (geometrically). An area is defined by one or more 
+boundaries that form a losed ring. The category to which an area belongs 
+is stored with the centroid. Such centroids are stored in the same binary
 'coor' file with other primitives. Each element may have none, one or
-more categories (cats). More cats are distinguished by field number
+more categories (cats). More cats can be distinguished by field number
 (field, called "layer" at user level).  Single and multi-category
-support on modules level are implemented. Z-coordinate is optional and
-both 2D and 3D files may be written.
+support on modules level are implemented. The z coordinate is optional 
+and both 2D and 3D files may be written.
 
 The following <em>vector feature types (primitives)</em> are defined
 by the vector library (and holds by the coor file; see also \ref
@@ -155,20 +157,118 @@ There are two levels of read access to the vector data:
   level.
 - <i>Level Two</i> provides full access to all the information
   including topology information. This level requires more from the
-  programmer, more memory, and longer startup time.
+  programmer, more memory, and longer startup time. Without this level,
+  areas are not available.
+
+The level of access is retured by Vect_open_old().
+
+<b>Example for sequential read access without topology:</b>
+\code
+int main
+{
+    int type, ltype;
+    struct Map_info Map;
+    struct line_pnts *Points;
+    struct line_cat *Cats;
+    const char *name, *mapset;
+
+    /* set open level to 1: no topology */
+    Vect_set_open_level(1);
+
+    if (Vect_open_old(&Map, name, mapset) < 1)
+	G_fatal_error(_("Failed to open vector '%s'"), name);
+
+    /* rewind vector file */
+    Vect_rewind(&Map);
+    
+    Points = Vect_new_line_struct();
+    Cats = Vect_new_cats_struct();
+
+    while ((ltype = Vect_read_next_line(&Map, Points, Cats) > 0) {
+    
+	/* check for desired type */
+	if (!(ltype & type))
+	    continue;
+
+	/* process the feature */
+    }
+
+    exit(EXIT_SUCCESS);
+}
+\endcode
+
+<b>Example for random read access with topology:</b>
+\code
+int main
+{
+    int line, nlines, type, ltype;
+    struct Map_info Map;
+    struct line_pnts *Points;
+    struct line_cat *Cats;
+    const char *name, *mapset;
+
+    if (Vect_open_old(&Map, name, mapset) < 2)
+	G_fatal_error(_("Failed to open vector '%s'"), name);
+
+    Points = Vect_new_line_struct();
+    Cats = Vect_new_cats_struct();
+    
+    nlines = Vect_get_num_lines(&Map);
+    for (line = 1; line <= nlines; line++) {
+    
+	/* check for desired type */
+	if (!(Vect_get_line_type(&Map, line) & type))
+	    continue;
+
+    	Vect_read_line(&Map, points, cats, line);
+
+	/* process the feature */
+    }
+    
+    exit(EXIT_SUCCESS);
+}
+\endcode
+
+
+<b>Example for working with areas (requires topology):</b>
+\code
+int main
+{
+    int area, nareas;
+    struct Map_info Map;
+    struct line_cat *Cats;
+    const char *name, *mapset;
+
+    if (Vect_open_old(&Map, name, mapset) < 2)
+	G_fatal_error(_("Failed to open vector '%s'"), name);
+
+    Points = Vect_new_line_struct();
+    Cats = Vect_new_cats_struct();
+    
+    nareas = Vect_get_num_areas(&Map);
+    for (area = 1; area <= nareas; area++) {
+
+	/* process the area */
+	/* example: get area categories */
+	if (Vect_get_area_cats(&Map, area, Cats) == -1)
+	    G_message(_("No catagory available for area %d"), area);
+    }
+    
+    exit(EXIT_SUCCESS);
+}
+\endcode
 
-Level of access is retured by Vect_open_old().
 
 <em>Note:</em> Higher level of access are planned, so when checking
 success return codes for a particular level of access (when calling
 Vect_open_old() for example), the programmer should use >= instead of
 == for compatibility with future releases.
 
-An existing vector map can be open for reading by Vect_open_old(). New
-vector map can be created (or open for writing) by
+An existing vector map can be opened for reading by Vect_open_old(). 
+A new vector map can be created (or open for writing) by
 Vect_open_new(). Vect_open_old() attempts to open a vector map at the
 highest possible level of access. It will return the number of the
-level at which it opened. Vect_open_new() always opens at level 1
+level at which the map was opened. Vect_open_new() always opens at level 1
 only. If you require that a vector map be opened at a lower level
 (e.g. one), you can call the routine <tt>Vect_set_open_level(1)</tt>;
 Vect_open_old() will then either open at level one or fail. If you