[GRASS-SVN] r52237 - grass/trunk/lib/segment
svn_grass at osgeo.org
svn_grass at osgeo.org
Wed Jun 27 01:24:51 PDT 2012
Author: wenzeslaus
Date: 2012-06-27 01:24:50 -0700 (Wed, 27 Jun 2012)
New Revision: 52237
Modified:
grass/trunk/lib/segment/segmentlib.dox
Log:
segment lib: dox: more doxygen-style syntax to produce standardized output
Modified: grass/trunk/lib/segment/segmentlib.dox
===================================================================
--- grass/trunk/lib/segment/segmentlib.dox 2012-06-27 07:02:02 UTC (rev 52236)
+++ grass/trunk/lib/segment/segmentlib.dox 2012-06-27 08:24:50 UTC (rev 52237)
@@ -3,13 +3,11 @@
by M. Neteler 8/2005
-->
-\section segmentintro Segment Library
+\author CERL
+\section segmentintro Introduction
<P>
-Authors: CERL
-
-<P>
Large data files which contain data in a matrix format often need to be
accessed in a nonsequential or random manner. This requirement complicates
the programming.
@@ -61,9 +59,8 @@
data is paged into memory as needed and the requested data is returned to
the caller.
-<P>
-<B>Note:</B> All routines and global variables in this library, documented
-or undocumented, start with the prefix <B>segment_.</B> To avoid name
+\note All routines and global variables in this library, documented
+or undocumented, start with the prefix \c segment_. To avoid name
conflicts, programmers should not create variables or routines in their own
modules which use this prefix.
@@ -74,13 +71,15 @@
The routines in the <I>Segment Library</I> are described below, more or
less in the order they would logically be used in a module. They use a data
structure called SEGMENT which is defined in the header file
-<grass/segment.h> that must be included in any code using these
-routines: [footnote]
+\c grass/segment.h that must be included in any code using these
+routines:
-\verbatim
+\code
#include <grass/segment.h>
-\endverbatim
+\endcode
+\see \ref Loading_the_Segment_Library.
+
<P>
A temporary file needs to be prepared and a SEGMENT structure needs to
be initialized before any data can be transferred to the segment file.
@@ -131,22 +130,21 @@
<P>
The next step is to initialize a SEGMENT structure to be associated with a
-segment file formatted by <I>segment_format.</I>
+segment file formatted by segment_format().
<P>
<I>int segment_init (SEGMENT *seg, int fd, int nsegs)</I>, initialize segment
structure
<P>
Initializes the <B>seg</B> structure. The file on <B>fd</B> is
- a segment file created by <I>segment_format</I> and must be open for
+ a segment file created by segment_format() and must be open for
reading and writing. The segment file configuration parameters <I>nrows,
ncols, srows, scols</I>, and <I>len</I>, as written to the file by
<I>segment_format</I>, are read from the file and stored in the
<B>seg</B> structure. <B>Nsegs</B> specifies the number of segments that
will be retained in memory. The minimum value allowed is 1.
-<P>
-<B>Note.</B> The size of a segment is <I>scols*srows*len</I> plus a few
+\note The size of a segment is <I>scols*srows*len</I> plus a few
bytes for managing each segment.
<P>
@@ -161,7 +159,7 @@
<P>
Transfers nonsegmented matrix data, row by row, into a segment
file. <B>Seg</B> is the segment structure that was configured from a call
- to <I>segment_init.</I> <B>Buf</B> should contain <I>ncols*len</I>
+ to segment_init(). <B>Buf</B> should contain <I>ncols*len</I>
bytes of data to be transferred to the segment file. <B>Row</B> specifies
the row from the data matrix being transferred.
@@ -206,10 +204,10 @@
<P>
<I>int segment_flush (SEGMENT *seg)</I>, flush pending updates to disk
<P>
- Forces all pending updates generated by <I>segment_put()</I> to be
+ Forces all pending updates generated by segment_put() to be
written to the segment file <B>seg.</B> Must be called after the final
segment_put() to force all pending updates to disk. Must also be called
- before the first call to <I>segment_get_row.</I>
+ before the first call to segment_get_row().
<P>
Now the data in segment file can be read row by row and transferred to a normal
@@ -221,7 +219,7 @@
<P>
Transfers data from a segment file, row by row, into memory
(which can then be written to a regular matrix file) . <B>Seg</B> is the
- segment structure that was configured from a call to <I>segment_init.</I>
+ segment structure that was configured from a call to segment_init().
<B>Buf</B> will be filled with <I>ncols*len</I> bytes of data
corresponding to the <B>row</B> in the data matrix.
@@ -236,7 +234,7 @@
<P>
Releases the allocated memory associated with the segment file
<B>seg.</B> Does not close the file. Does not flush the data which may
- be pending from previous <I>segment_put()</I> calls.
+ be pending from previous segment_put() calls.
<P>
@@ -259,81 +257,77 @@
Creation of a segment file and initialization of the segment structure
at once:
-\verbatim
-
+\code
SEGMENT seg;
segment_open (&seg, G_tempfile(), nrows, ncols, srows, scols, sizeof(int), nseg);
+\endcode
-\endverbatim
-
Alternatively, the first step is the creation and formatting of a segment
file. A file is created, formatted and then closed:
-\verbatim
+\code
fd = creat (file, 0666);
segment_format (fd, nrows, ncols, srows, scols, sizeof(int));
close(fd);
-\endverbatim
+\endcode
<P>
The next step is the conversion of the nonsegmented matrix data into segment
file format. The segment file is reopened for read and write and initialized:
-\verbatim
+\code
#include <fcntl.h>
SEGMENT seg;
fd = open (file, O_RDWR);
segment_init (&seg, fd, nseg);
+\endcode
-\endverbatim
-
<P>
Both the segment file and the segment structure are now ready to use, and
data can be read row by row from the original data file and put into the
segment file:
-\verbatim
-
+\code
for (row = 0; row < nrows; row++)
{
- <code to get original matrix data for row into buf>
+ // code to get original matrix data for row into buf
segment_put_row (&seg, buf, row);
}
-\endverbatim
+\endcode
<P>
Of course if the intention is only to add new values rather than update existing
values, the step which transfers data from the original matrix to the segment
-file, using segment_put_row() , could be omitted, since
-<I>segment_format</I> will fill the segment file with zeros.
+file, using segment_put_row(), could be omitted, since
+segment_format() will fill the segment file with zeros.
<P>
-The data can now be accessed directly using <I>segment_get.</I> For example,
+The data can now be accessed directly using segment_get(). For example,
to get the value at a given row and column:
-\verbatim
+\code
int value;
SEGMENT seg;
segment_get (&seg, &value, row, col);
-\endverbatim
+\endcode
<P>
-Similarly <I>segment_put()</I> can be used to change data values in the
+Similarly segment_put() can be used to change data values in the
segment file:
-\verbatim
+\code
int value;
SEGMENT seg;
@@ -341,16 +335,16 @@
value = 10;
segment_put (&seg, &value, row, col);
-\endverbatim
+\endcode
-<P>
-<B>WARNING:</B> It is an easy mistake to pass a value directly to
+
+\warning It is an easy mistake to pass a value directly to
segment_put(). The following should be avoided:
-\verbatim
-segment_put (&seg, 10, row, col); /* this will not work */
-\endverbatim
+\code
+segment_put (&seg, 10, row, col); // this will not work
+\endcode
<P>
Once the random access processing is complete, the data would be extracted
@@ -358,30 +352,30 @@
follows:
-\verbatim
+\code
segment_flush (&seg);
for (row = 0; row < nrows; row++)
{
segment_get_row (&seg, buf, row);
- <code to put buf into a matrix data file for row>
+ // code to put buf into a matrix data file for row
}
-\endverbatim
+\endcode
<P>
Finally, the memory allocated for use by the segment routines would be
released and the file closed:
-\verbatim
+\code
segment_release (&seg);
close (fd);
-\endverbatim
+\endcode
-<P>
-<B>Note:</B> The <I>Segment Library</I> does not know the name of the
+
+\note The <I>Segment Library</I> does not know the name of the
segment file. It does not attempt to remove the file. If the file is only
temporary, the programmer should remove the file after closing it.
@@ -403,9 +397,9 @@
<P>
The library is loaded by specifying
-\verbatim
+\code
$(SEGMENTLIB)
-\endverbatim
+\endcode
in the Makefile.
<P>
More information about the grass-commit
mailing list