[GRASS-SVN] r32610 - grass/trunk/lib/gis
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Aug 7 06:47:53 EDT 2008
Author: martinl
Date: 2008-08-07 06:47:52 -0400 (Thu, 07 Aug 2008)
New Revision: 32610
Modified:
grass/trunk/lib/gis/get_cellhd.c
grass/trunk/lib/gis/open.c
grass/trunk/lib/gis/opencell.c
Log:
gislib: doxygen clean-up (open*.c files)
message standardization
(merge from devbr6, r32609)
Modified: grass/trunk/lib/gis/get_cellhd.c
===================================================================
--- grass/trunk/lib/gis/get_cellhd.c 2008-08-07 10:22:49 UTC (rev 32609)
+++ grass/trunk/lib/gis/get_cellhd.c 2008-08-07 10:47:52 UTC (rev 32610)
@@ -1,15 +1,13 @@
/*!
- \file get_cellhd.c
-
- \brief GIS library - Read raster header
-
- (C) 2001-2008 by the GRASS Development Team
-
- This program is free software under the
- GNU General Public License (>=v2).
- Read the file COPYING that comes with GRASS
- for details.
-
+ \file gis/get_cellhd.c
+
+ \brief GIS library - Read raster map header
+
+ (C) 2001-2008 by the GRASS Development Team
+
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
+
\author Original author CERL
*/
@@ -19,29 +17,29 @@
#include <grass/glocale.h>
/*!
- * \brief Read the raster header
- *
- * The raster header for the raster map <b>name</b> in the specified
- * <b>mapset</b> is read into the <b>cellhd</b> structure. If there
- * is an error reading the raster header file, a diagnostic message is
- * printed and -1 is returned. Otherwise, 0 is returned.
- *
- * <b>Note</b>:a warning message for errors encountered.
- *
- * Cell header files may contain either grid cell header
- * information or reclass information. If it is a reclass
- * file, it will specify the map and mapset names of the actual
- * grid cell file being reclassed. G_get_cellhd(), upon
- * reading reclass information will go read the cell header
- * information for the referenced file. Only one reference is
- * allowed.
- *
- * \param name name of map
- * \param mapset mapset that map belongs to
- * \param cellhd structure to hold cell header info
- *
- * \return 0 on success
- * \return -1 on error
+ \brief Read the raster header
+
+ The raster header for the raster map <i>name</i> in the specified
+ <i>mapset</i> is read into the <i>cellhd</i> structure. If there is
+ an error reading the raster header file, a diagnostic message is
+ printed and -1 is returned. Otherwise, 0 is returned.
+
+ <b>Note</b>:a warning message for errors encountered.
+
+ Cell header files may contain either grid cell header
+ information or reclass information. If it is a reclass
+ file, it will specify the map and mapset names of the actual
+ grid cell file being reclassed. G_get_cellhd(), upon
+ reading reclass information will go read the cell header
+ information for the referenced file. Only one reference is
+ allowed.
+
+ \param name name of map
+ \param mapset mapset that map belongs to
+ \param cellhd structure to hold cell header info
+
+ \return 0 on success
+ \return -1 on error
*/
int G_get_cellhd(const char *name, const char *mapset,
@@ -87,10 +85,8 @@
else {
fd = G_fopen_old("cellhd", name, mapset);
if (fd == NULL) {
- sprintf(buf,
- _("Unable to open header file for raster map <%s@%s>"),
- name, mapset);
- G_warning(buf);
+ G_warning(_("Unable to open header file for raster map <%s@%s>"),
+ name, mapset);
return -1;
}
}
Modified: grass/trunk/lib/gis/open.c
===================================================================
--- grass/trunk/lib/gis/open.c 2008-08-07 10:22:49 UTC (rev 32609)
+++ grass/trunk/lib/gis/open.c 2008-08-07 10:47:52 UTC (rev 32610)
@@ -1,76 +1,16 @@
-/*
- *****************************************************************
- * open routines
- *
- * G__open (element, name, mapset, mode)
- * char *element database element name
- * char *name map file name
- * char *mapset mapset containing map "name"
- * int mode 0=read, 1=write, 2=read/write
+/*!
+ * \file gis/open.c
*
- * this is the lowest level open routine.
- * opens the file 'name' in 'element' ("cell", etc)
- * in mapset 'mapset' according to the i/o 'mode'
+ * \brief GIS Library - open file functions
*
- * mode = 0 (read) will look for 'name' in 'mapset'
- * and open the file for read only
- * the file must exist
+ * (C) 1999-2008 by the GRASS Development Team
*
- * mode = 1 (write) will create an empty file 'name' in the
- * current mapset and open the file for write only
- * 'mapset' ignored
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- * mode = 2 (read and write) will open a file in the
- * current mapset for reading and writing
- * creating a new file if necessary
- * 'mapset' ignored
- *
- * returns: open file descriptor (int)
- * or -1 could not open
- *
- *******************************************************************
- * G_open_new (element, name)
- * char *element database element name
- * char *name map file name
- *
- * creates 'name' in the current mapset and opens it
- * for write only.
- *
- * returns: open file descriptor (int)
- * or -1 could not open
- *
- *******************************************************************
- * G_open_old (element, name, mapset)
- * char *element database element name
- * char *name map file name
- * char *mapset mapset containing map "name"
- *
- * opens 'name' in 'mapset' for read only.
- *
- * returns: open file descriptor (int)
- * or -1 could not open
- *
- *******************************************************************
- * G_fopen_new (element, name)
- * char *element database element name
- * char *name map file name
- *
- * creates 'name' in the current mapset and opens it
- * for write only.
- *
- * returns: open file descriptor (FILE *)
- * or NULL could not open
- *
- *******************************************************************
- * G_fopen_old (element, name, mapset)
- * char *element database element name
- * char *name map file name
- *
- * opens 'name' in 'mapset' for read only.
- *
- * returns: open file descriptor (FILE *)
- * or NULL could not open
- *******************************************************************/
+ * \author USACERL and many others
+ */
#include <grass/config.h>
#include <string.h>
@@ -79,10 +19,37 @@
#include <unistd.h>
#endif
-#include <grass/gis.h>
#include <unistd.h>
#include <fcntl.h>
+#include <grass/gis.h>
+#include <grass/glocale.h>
+
+/*!
+ \brief Lowest level open routine.
+
+ Opens the file <i>name</i> in <i>element</i> ("cell", etc.) in mapset <i>mapset</i>
+ according to the i/o <i>mode</i>.
+
+ - mode = 0 (read) will look for <i>name</i> in <i>mapset</i> and
+ open the file for read only the file must exist
+
+ - mode = 1 (write) will create an empty file <i>name</i> in the
+ current mapset and open the file for write only
+ <i>mapset</i> ignored
+
+ - mode = 2 (read and write) will open a file in the current mapset
+ for reading and writing creating a new file if
+ necessary <i>mapset</i> ignored
+
+ \param element database element name
+ \param name map file name
+ \param mapset mapset containing map <i>name</i>
+ \param mode r/w mode 0=read, 1=write, 2=read/write
+
+ \return open file descriptor (int)
+ \return -1 could not open
+*/
static int G__open(const char *element,
const char *name, const char *mapset, int mode)
{
@@ -96,9 +63,8 @@
if (mode == 0) {
if (G__name_is_fully_qualified(name, xname, xmapset)) {
if (strcmp(xmapset, mapset) != 0) {
- fprintf(stderr,
- "G__open(r): mapset (%s) doesn't match xmapset (%s)\n",
- mapset, xmapset);
+ G_warning(_("G__open(read): mapset <%s> doesn't match xmapset <%s>"),
+ mapset, xmapset);
return -1;
}
name = xname;
@@ -113,9 +79,8 @@
if (mode == 1 || mode == 2) {
if (G__name_is_fully_qualified(name, xname, xmapset)) {
if (strcmp(xmapset, G_mapset()) != 0) {
- fprintf(stderr,
- "G__open(w): xmapset (%s) != G_mapset() (%s)\n",
- xmapset, G_mapset());
+ G_warning(_("G__open(write): xmapset <%s> != G_mapset() <%s>"),
+ xmapset, G_mapset());
return -1;
}
name = xname;
@@ -135,21 +100,25 @@
return -1;
}
-
/*!
- * \brief open a new database file
- *
- * The database file <b>name</b> under the <b>element</b> in the
- * current mapset is created and opened for writing (but not reading).
- * The UNIX open( ) routine is used to open the file. If the file does not exist,
- * -1 is returned. Otherwise the file is positioned at the end of the file and
- * the file descriptor from the open( ) is returned.
- *
- * \param element
- * \param name
- * \return int
- */
+ \brief Open a new database file
+ Creates <i>name</i> in the current mapset and opens it
+ for write only.
+
+ The database file <i>name</i> under the <i>element</i> in the
+ current mapset is created and opened for writing (but not reading).
+ The UNIX open() routine is used to open the file. If the file does
+ not exist, -1 is returned. Otherwise the file is positioned at the
+ end of the file and the file descriptor from the open() is returned.
+
+ \param element database element name
+ \param name map file name
+
+ \return open file descriptor (int)
+ \return -1 could not open
+*/
+
int G_open_new(const char *element, const char *name)
{
return G__open(element, name, G_mapset(), 1);
@@ -157,38 +126,40 @@
/*!
- * \brief open a database file for reading
- *
- * The database file <b>name</b> under the
- * <b>element</b> in the specified <b>mapset</b> is opened for reading (but
- * not for writing).
- * The UNIX open( ) routine is used to open the file. If the file does not exist,
- * -1 is returned. Otherwise the file descriptor from the open( ) is returned.
- *
- * \param element
- * \param name
- * \param mapset
- * \return int
- */
+ \brief Open a database file for reading
+
+ The database file <i>name</i> under the <i>element</i> in the
+ specified <i>mapset</i> is opened for reading (but not for writing).
+ The UNIX open() routine is used to open the file. If the file does
+ not exist, -1 is returned. Otherwise the file descriptor from the
+ open() is returned.
+
+ \param element database element name
+ \param name map file name
+ \param mapset mapset containing map <i>name</i>
+ \return open file descriptor (int)
+ \return -1 could not open
+*/
int G_open_old(const char *element, const char *name, const char *mapset)
{
return G__open(element, name, mapset, 0);
}
+/*!
+ \brief Open a database file for update
+
+ The database file <i>name</i> under the <i>element</i> in the
+ current mapset is opened for reading and writing. The UNIX open()
+ routine is used to open the file. If the file does not exist, -1 is
+ returned. Otherwise the file is positioned at the end of the file
+ and the file descriptor from the open() is returned.
+
+ \param element database element name
+ \param name map file name
-/*!
- * \brief open a database file for update
- *
- * The database file <b>name</b> under the <b>element</b> in the
- * current mapset is opened for reading and writing.
- * The UNIX open( ) routine is used to open the file. If the file does not exist,
- * -1 is returned. Otherwise the file is positioned at the end of the file and
- * the file descriptor from the open( ) is returned.
- *
- * \param element
- * \param name
- * \return int
+ \return open file descriptor (int)
+ \return -1 could not open
*/
int G_open_update(const char *element, const char *name)
@@ -204,18 +175,20 @@
/*!
- * \brief open a new database file
- *
- * The database file <b>name</b> under the <b>element</b> in the
- * current mapset is created and opened for writing (but not reading).
- * The UNIX fopen( ) routine, with "w" write mode, is used to open the file. If
- * the file does not exist, the NULL pointer is returned. Otherwise the file is
- * positioned at the end of the file and the file descriptor from the fopen( ) is
- * returned.
- *
- * \param element
- * \param name
- * \return FILE *
+ \brief Open a new database file
+
+ The database file <i>name</i> under the <i>element</i> in the
+ current mapset is created and opened for writing (but not reading).
+ The UNIX fopen() routine, with "w" write mode, is used to open the
+ file. If the file does not exist, the NULL pointer is
+ returned. Otherwise the file is positioned at the end of the file
+ and the file descriptor from the fopen() is returned.
+
+ \param element database element name
+ \param name map file name
+
+ \return open file descriptor (FILE *)
+ \return NULL could not open
*/
FILE *G_fopen_new(const char *element, const char *name)
@@ -231,21 +204,22 @@
/*!
- * \brief open a database file for reading
- *
- * The database file <b>name</b> under the
- * <b>element</b> in the specified <b>mapset</b> is opened for reading (but
- * not for writing).
- * The UNIX fopen( ) routine, with "r" read mode, is used to open the file. If
- * the file does not exist, the NULL pointer is returned. Otherwise the file
- * descriptor from the fopen( ) is returned.
- *
- * \param element
- * \param name
- * \param mapset
- * \return FILE *
- */
+ \brief Open a database file for reading
+
+ The database file <i>name</i> under the <i>element</i> in the
+ specified <i>mapset</i> is opened for reading (but not for writing).
+ The UNIX fopen() routine, with "r" read mode, is used to open the
+ file. If the file does not exist, the NULL pointer is
+ returned. Otherwise the file descriptor from the fopen() is
+ returned.
+
+ \param element database element name
+ \param name map file name
+ \param mapset mapset name containing map <i>name</i>
+ \return open file descriptor (FILE *)
+ \return NULL could not open
+*/
FILE *G_fopen_old(const char *element, const char *name, const char *mapset)
{
int fd;
@@ -257,6 +231,21 @@
return fdopen(fd, "r");
}
+/*!
+ \brief Open a database file for update (append mode)
+
+ The database file <i>name</i> under the <i>element</i> in the
+ current mapset is opened for for writing. The UNIX fopen() routine,
+ with "a" append mode, is used to open the file. If the file does not
+ exist, the NULL pointer is returned. Otherwise the file descriptor
+ from the fopen() is returned.
+
+ \param element database element name
+ \param name map file name
+
+ \return open file descriptor (FILE *)
+ \return NULL could not open
+*/
FILE *G_fopen_append(const char *element, const char *name)
{
int fd;
@@ -269,6 +258,21 @@
return fdopen(fd, "a");
}
+/*!
+ \brief Open a database file for update (r+ mode)
+
+ The database file <i>name</i> under the <i>element</i> in the
+ current mapset is opened for for writing. The UNIX fopen() routine,
+ with "r+" append mode, is used to open the file. If the file does not
+ exist, the NULL pointer is returned. Otherwise the file descriptor
+ from the fopen() is returned.
+
+ \param element database element name
+ \param name map file name
+
+ \return open file descriptor (FILE *)
+ \return NULL
+*/
FILE *G_fopen_modify(const char *element, const char *name)
{
int fd;
Modified: grass/trunk/lib/gis/opencell.c
===================================================================
--- grass/trunk/lib/gis/opencell.c 2008-08-07 10:22:49 UTC (rev 32609)
+++ grass/trunk/lib/gis/opencell.c 2008-08-07 10:47:52 UTC (rev 32610)
@@ -1,101 +1,16 @@
-
-/**********************************************************
- *
- * G_open_cell_old (name, mapset)
- * char *name map file name
- * char *mapset mapset containing map "name"
- *
- * opens the existing cell file 'name' in the 'mapset'
- * for reading by G_get_map_row()
- * with mapping into the current window
- *
- * returns: open file descriptor ( >= 0) if successful
- * negative integer if error
- *
- * diagnostics: warning message printed if open fails
- ***********************************************************
- *
- * G_open_cell_new (name)
- * char *name map file name
- *
- * opens a new cell file 'name' in the current mapset
- * for writing by G_put_map_row()
- *
- * the file is created and filled with no data
- * it is assumed that the new cell file is to conform to
- * the current window.
- *
- * The file must be written sequentially.
- * (Use G_open_cell_new_random() for non sequential writes)
- *
- * note: the open actually creates a temporary file
- * G_close_cell() will move the temporary file
- * to the cell file and write out the necessary
- * support files (cellhd, cats, hist, etc.)
- *
- * returns: open file descriptor ( >= 0) if successful
- * negative integer if error
- *
- * diagnostics: warning message printed if open fails
- *
- * warning: calls to G_set_window() made after opening a new
- * cell file may create confusion and should be avoided
- * the new cell file will be created to conform
- * to the window at the time of the open.
- ***********************************************************
- *
- * G_open_fp_cell_new (name)
- * char *name map file name
- *
- * opens a new floating-point map "name" in the current mapset for writing. The type
- * of the file (i.e. either double or float) is determined and fixed at
- * this point. The default is FCELL_TYPE. In order to change this default
- * USE G_set_fp_type(type) where type is one of DCELL_TYPE or FCELL_TYPE..
- * see warnings and notes for G_open_cell_new
- *
- ***********************************************************
- *
- * G_open_raster_new(char *name, RASTER_MAP_TYPE map_type
- *
- * opens a new raster map of type map_type
- * see warnings and notes for G_open_cell_new
- *
- ***********************************************************
- *
- * RASTER_MAP_TYPE G_raster_map_type(name, mapset)
- * returns the type of raster map: DCELL_TYPE, FCELL_TYPE or CELL_TYPE
- *
- ***********************************************************
- *
+/*!
+ * \file gis/opencell.c
*
- * int G_raster_map_is_fp(name, set)
- * returns 1 if map is float or double, 0 otherwise
+ * \brief GIS Library - open raster (cell) file functions
*
- ***********************************************************
- * G_set_cell_format(n)
+ * (C) 1999-2008 by the GRASS Development Team
*
- * sets the format for subsequent opens on new integer cell files
- * (uncompressed and random only)
- * warning - subsequent put_row calls will only write n+1 bytes
- * per cell. If the data requires more, the cell file
- * will be written incorrectly (but with n+1 bytes per cell)
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- ***********************************************************
- * G_set_quant_rules(int fd, struct Quant q)
- *
- * Sets quant translation rules for raster map opened for reading.
- * fd is a file descriptor returned by G_open_cell_old().
- * After calling this function, G_get_c_raster_row() and
- * G_get_map_row() will use rules defined by q (instead of using
- * rules defined in map's quant file) to convert floats to ints.
- *
- ***********************************************************
- * G_want_histogram(flag)
- *
- * If newly created cell files should have histograms, set flag=1
- * otherwise set flag=0. Applies to subsequent opens.
- *
- ***********************************************************/
+ * \author USACERL and many others
+ */
#include <rpc/types.h>
#include <rpc/xdr.h>
@@ -135,27 +50,7 @@
return &G__.fileinfo[fd];
}
-/*!
- * \brief open an existing raster map
- *
- * This routine opens the raster map <b>name</b> in
- * <b>mapset</b> for reading. A nonnegative file descriptor is returned if the
- * open is successful. Otherwise a diagnostic message is printed and a negative
- * value is returned. This routine does quite a bit of work. Since GRASS users
- * expect that all raster maps will be resampled into the current region, the
- * resampling index for the raster map is prepared by this routine after the
- * file is opened. The resampling is based on the active module
- * region.\remarks{See also The_Region.} Preparation required for
- * reading the various raster file formats\remarks{See
- * Raster_File_Format for an explanation of the various raster file
- * formats.} is also done.
- *
- * \param name
- * \param mapset
- * \return int
- */
-
/*!
* \brief
*
@@ -172,15 +67,40 @@
* \return int
*/
-
static int G__open_raster_new(const char *name, int open_mode);
+/*!
+ \brief Open an existing integer raster map (cell)
+
+ Opens the existing cell file <i>name</i> in the <i>mapset</i> for
+ reading by G_get_raster_row() with mapping into the current window.
+
+ This routine opens the raster map <i>name</i> in <i>mapset</i> for
+ reading. A nonnegative file descriptor is returned if the open is
+ successful. Otherwise a diagnostic message is printed and a negative
+ value is returned. This routine does quite a bit of work. Since
+ GRASS users expect that all raster maps will be resampled into the
+ current region, the resampling index for the raster map is prepared
+ by this routine after the file is opened. The resampling is based on
+ the active module region.\remarks{See also The_Region.} Preparation
+ required for reading the various raster file formats\remarks{See
+ Raster_File_Format for an explanation of the various raster file
+ formats.} is also done.
+
+ Diagnostics: warning message printed if open fails.
+
+ \param name map name
+ \param mapset mapset name where raster map <i>name</i> lives
+
+ \return nonnegative file descriptor (int)
+ \return -1 on failure
+ */
int G_open_cell_old(const char *name, const char *mapset)
{
int fd;
if ((fd = G__open_cell_old(name, mapset)) < 0) {
- G_warning(_("unable to open raster map [%s in %s]"), name, mapset);
+ G_warning(_("Unable to open raster map <%s@%s>"), name, mapset);
return fd;
}
@@ -197,37 +117,33 @@
return fd;
}
+/*!
+ \brief Lower level function, open cell files, supercell
+ files, and the MASK file.
-/********************************************************************
- * G__open_cell_old (name, mapset)
- *
- * function:
- * This is the work horse. It is used to open cell files, supercell
- * files, and the MASK file.
- *
- * parms:
- * name, mapset name and mapset of cell file to be opened.
- *
- * actions:
- * opens the named cell file, following reclass reference if
- * named layer is a reclass layer.
- * creates the required mapping between the data and the window
- * for use by the get_map_row family of routines.
- *
- * returns:
- * open file descriptor or -1 if error.
- *
- * diagnostics:
- * errors other than actual open failure will cause a diagnostic to be
- * delivered thru G_warning() open failure messages are left to the
- * calling routine since the masking logic will want to issue a different
- * warning.
- *
- * note:
- * this routine does NOT open the MASK layer. If it did we would get
- * infinite recursion. This routine is called to open the mask by
- * G__check_for_auto_masking() which is called by G_open_cell().
- ***********************************************************************/
+ Actions:
+ - opens the named cell file, following reclass reference if
+ named layer is a reclass layer.
+ - creates the required mapping between the data and the window
+ for use by the get_map_row family of routines.
+
+ Diagnostics:
+ Errors other than actual open failure will cause a diagnostic to be
+ delivered thru G_warning() open failure messages are left to the
+ calling routine since the masking logic will want to issue a different
+ warning.
+
+ Note:
+ This routine does NOT open the MASK layer. If it did we would get
+ infinite recursion. This routine is called to open the mask by
+ G__check_for_auto_masking() which is called by G_open_cell_old().
+
+ \param name map name
+ \param mapset mapset of cell file to be opened
+
+ \return open file descriptor
+ \return -1 if error
+*/
int G__open_cell_old(const char *name, const char *mapset)
{
struct fileinfo *fcb;
@@ -258,7 +174,8 @@
r_name = reclass.name;
r_mapset = reclass.mapset;
if (G_find_cell2(r_name, r_mapset) == NULL) {
- G_warning(_("unable to open [%s] in [%s] since it is a reclass of [%s] in [%s] which does not exist"),
+ G_warning(_("Unable to open raster map <%s@%s> since it is a reclass "
+ "of raster map <%s@%s> which does not exist"),
name, mapset, r_name, r_mapset);
return -1;
}
@@ -281,27 +198,28 @@
{
CELL_nbytes = cellhd.format + 1;
if (CELL_nbytes < 1) {
- G_warning(_("[%s] in mapset [%s]-format field in header file invalid"),
+ G_warning(_("Raster map <%s@%s>: format field in header file invalid"),
r_name, r_mapset);
return -1;
}
}
if (cellhd.proj != G__.window.proj) {
- G_warning(_("[%s] in mapset [%s] - in different projection than current region:\n found map [%s] in: <%s>, should be <%s> "),
+ G_warning(_("Raster map <%s@%s> is in different projection than current region. "
+ "Found raster map <%s@%s>, should be <%s>."),
name, mapset, name, G__projection_name(cellhd.proj),
G__projection_name(G__.window.proj));
return -1;
}
if (cellhd.zone != G__.window.zone) {
- G_warning(_("[%s] in mapset [%s] - in different zone [%d] than current region [%d]"),
+ G_warning(_("Raster map <%s@%s> is in different zone (%d) than current region (%d)"),
name, mapset, cellhd.zone, G__.window.zone);
return -1;
}
/* when map is int warn if too large cell size */
- if (MAP_TYPE == CELL_TYPE && CELL_nbytes > sizeof(CELL)) {
- G_warning(_("[%s] in [%s] - bytes per cell (%d) too large"),
+ if (MAP_TYPE == CELL_TYPE && (unsigned int) CELL_nbytes > sizeof(CELL)) {
+ G_warning(_("Raster map <%s@%s>: bytes per cell (%d) too large"),
name, mapset, CELL_nbytes);
return -1;
}
@@ -443,9 +361,33 @@
static char cell_dir[100];
-/* The mapset element for the raster map to be open: fcell, or cell */
+/*!
+ \brief Opens a new cell file in a database (compressed)
+ Opens a new cell file <i>name</i> in the current mapset for writing
+ by G_put_raster_row().
+
+ The file is created and filled with no data it is assumed that the
+ new cell file is to conform to the current window.
+
+ The file must be written sequentially. Use G_open_cell_new_random()
+ for non sequential writes.
+
+ Note: the open actually creates a temporary file G_close_cell() will
+ move the temporary file to the cell file and write out the necessary
+ support files (cellhd, cats, hist, etc.).
+ Diagnostics: warning message printed if open fails
+
+ Warning: calls to G_set_window() made after opening a new cell file
+ may create confusion and should be avoided the new cell file will be
+ created to conform to the window at the time of the open.
+
+ \param name map name
+
+ \return open file descriptor ( >= 0) if successful
+ \return negative integer if error
+*/
int G_open_cell_new(const char *name)
{
WRITE_MAP_TYPE = CELL_TYPE;
@@ -455,6 +397,18 @@
return G__open_raster_new(name, OPEN_NEW_COMPRESSED);
}
+/*!
+ \brief Opens a new cell file in a database (random mode)
+
+ See also G_open_cell_new().
+
+ Used for non sequential writes.
+
+ \param name map name
+
+ \return open file descriptor ( >= 0) if successful
+ \return negative integer if error
+*/
int G_open_cell_new_random(const char *name)
{
WRITE_MAP_TYPE = CELL_TYPE;
@@ -464,6 +418,16 @@
return G__open_raster_new(name, OPEN_NEW_RANDOM);
}
+/*!
+ \brief Opens a new cell file in a database (uncompressed)
+
+ See also G_open_cell_new().
+
+ \param name map name
+
+ \return open file descriptor ( >= 0) if successful
+ \return negative integer if error
+*/
int G_open_cell_new_uncompressed(const char *name)
{
WRITE_MAP_TYPE = CELL_TYPE; /* a type of current map */
@@ -473,6 +437,16 @@
return G__open_raster_new(name, OPEN_NEW_UNCOMPRESSED);
}
+/*!
+ \brief Save histogram for newly create raster map (cell)
+
+ If newly created cell files should have histograms, set flag=1
+ otherwise set flag=0. Applies to subsequent opens.
+
+ \param flag flag indicator
+
+ \return 0
+*/
int G_want_histogram(int flag)
{
G__.want_histogram = flag;
@@ -480,7 +454,20 @@
return 0;
}
-/* when writing float map: format is -1 */
+/*!
+ \brief Sets the format for subsequent opens on new integer cell files
+ (uncompressed and random only).
+
+ Warning: subsequent put_row calls will only write n+1 bytes
+ per cell. If the data requires more, the cell file
+ will be written incorrectly (but with n+1 bytes per cell)
+
+ When writing float map: format is -1
+
+ \param n format
+
+ \return 0
+*/
int G_set_cell_format(int n)
/* sets the format for integer raster map */
{
@@ -488,16 +475,23 @@
NBYTES = n + 1;
if (NBYTES <= 0)
NBYTES = 1;
- if (NBYTES > sizeof(CELL))
+ if ((unsigned int) NBYTES > sizeof(CELL))
NBYTES = sizeof(CELL);
}
return 0;
}
+/*!
+ \brief Get cell value format
+
+ \param v cell
+
+ \return cell format
+*/
int G_cellvalue_format(CELL v)
{
- int i;
+ unsigned int i;
if (v >= 0)
for (i = 0; i < sizeof(CELL); i++)
@@ -506,6 +500,23 @@
return sizeof(CELL) - 1;
}
+/*!
+ \brief Opens new fcell file in a database
+
+ Opens a new floating-point map <i>name</i> in the current mapset for
+ writing. The type of the file (i.e. either double or float) is
+ determined and fixed at this point. The default is FCELL_TYPE. In
+ order to change this default
+
+ Use G_set_fp_type() where type is one of DCELL_TYPE or FCELL_TYPE.
+
+ See warnings and notes for G_open_cell_new().
+
+ \param name map name
+
+ \return nonnegative file descriptor (int)
+ \return -1 on error
+*/
int G_open_fp_cell_new(const char *name)
{
/* use current float. type for writing float point maps */
@@ -528,6 +539,16 @@
return G__open_raster_new(name, OPEN_NEW_COMPRESSED);
}
+/*!
+ \brief Opens new fcell file in a database (uncompressed)
+
+ See G_open_fp_cell_new() for details.
+
+ \param name map name
+
+ \return nonnegative file descriptor (int)
+ \return -1 on error
+*/
int G_open_fp_cell_new_uncompressed(const char *name)
{
/* use current float. type for writing float point maps */
@@ -592,19 +613,20 @@
/* check for fully-qualfied name */
if (G__name_is_fully_qualified(name, xname, xmapset)) {
if (strcmp(xmapset, G_mapset()) != 0)
- G_fatal_error("%s is not in the current mapset (%s)", name,
- G_mapset());
+ G_fatal_error(_("Raster map <%s> is not in the current mapset (%s)"),
+ name, G_mapset());
name = xname;
}
/* check for legal grass name */
if (G_legal_filename(name) < 0) {
- G_warning(_("opencell: %s - illegal file name"), name);
+ G_warning(_("<%s> is an illegal file name"),
+ name);
return -1;
}
if (clean_check_raster_name(name, &map, &mapset) != 0) {
- G_warning("opencell: %s - bad mapset", name);
+ G_warning(_("<%s>: bad mapset"), name);
return -1;
}
@@ -615,7 +637,7 @@
tempname = G_tempfile();
fd = creat(tempname, 0666);
if (fd < 0) {
- G_warning("G__open_raster_new: no temp files available");
+ G_warning(_("G__open_raster_new(): no temp files available"));
G_free(tempname);
G_free(map);
G_free(mapset);
@@ -685,7 +707,8 @@
}
if (open_mode == OPEN_NEW_RANDOM) {
- G_warning(_("Can't write embedded null values for map open for random access"));
+ G_warning(_("Unable to write embedded null values "
+ "for raster map open for random access"));
if (fcb->map_type == CELL_TYPE)
G_write_zeros(fd,
(long)WRITE_NBYTES * fcb->cellhd.cols *
@@ -715,7 +738,7 @@
tempname = G_tempfile();
null_fd = creat(tempname, 0666);
if (null_fd < 0) {
- G_warning("opencell opening temp null file: no temp files available");
+ G_warning(_("G__open_raster_new(): no temp files available"));
G_free(tempname);
G_free(fcb->name);
G_free(fcb->mapset);
@@ -755,13 +778,15 @@
return fd;
}
-/*
- * allocate/enlarge the compressed data buffer needed by get_map_row()
- * and put_map_row()
- * note: compressed format is repeat, value:
- * repeat takes 1 byte, value takes up to sizeof(CELL)
- * plus 1 byte header for nbytes needed to store row
- */
+/*!
+ \brief allocate/enlarge the compressed data buffer needed by get_map_row()
+ and put_map_row()
+
+ Note: compressed format is repeat, value:
+
+ Repeat takes 1 byte, value takes up to sizeof(CELL)
+ plus 1 byte header for nbytes needed to store row
+*/
static int allocate_compress_buf(int fd)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -781,9 +806,13 @@
return 0;
}
-/*
- * allocate/enlarge the work data buffer needed by get_map_row and put_map_row()
- */
+/*!
+ \brief Allocate/enlarge the work data buffer needed by get_map_row and put_map_row()
+
+ \param bytes_per_cell number of bytes per cell
+
+ \return 0
+*/
int G__reallocate_work_buf(int bytes_per_cell)
{
int n;
@@ -801,10 +830,12 @@
return 0;
}
-/*
- * allocate/enlarge the null data buffer needed by get_map_row()
- * and for conversion in put_row
- */
+/*!
+ \brief Allocate/enlarge the null data buffer needed by get_map_row()
+ and for conversion in put_row
+
+ \return 0
+*/
int G__reallocate_null_buf(void)
{
int n;
@@ -820,9 +851,11 @@
return 0;
}
-/*
- * allocate/enlarge the mask buffer needed by get_map_row()
- */
+/*!
+ \brief Allocate/enlarge the mask buffer needed by get_map_row()
+
+ \return 0
+*/
int G__reallocate_mask_buf(void)
{
int n;
@@ -839,9 +872,11 @@
return 0;
}
-/*
- * allocate/enlarge the temporary buffer needed by G_get_raster_row[_nomask]
- */
+/*!
+ \brief Allocate/enlarge the temporary buffer needed by G_get_raster_row[_nomask]
+
+ \return 0
+*/
int G__reallocate_temp_buf(void)
{
int n;
@@ -860,23 +895,24 @@
/*!
- * \brief
- *
- * This controls the storage type for floating-point maps. It affects
- * subsequent calls to <tt>G_open_fp_map_new()</tt>. The <em>type</em>
- * must be one of <tt>FCELL_TYPE</tt> (float) or <tt>DCELL_TYPE</tt>
- * (double). The use of this routine by applications is discouraged
- * since its use would override user preferences.
- *
- * \param type
- * \return int
- */
+ \brief Set raster map floating-point data format.
+
+ This controls the storage type for floating-point maps. It affects
+ subsequent calls to G_open_fp_map_new(). The <em>type</em>
+ must be one of FCELL_TYPE (float) or DCELL_TYPE
+ (double). The use of this routine by applications is discouraged
+ since its use would override user preferences.
+
+ \param type raster data type
+
+ \return 1 on success
+ \return -1 on error
+*/
int G_set_fp_type(RASTER_MAP_TYPE map_type)
{
FP_TYPE_SET = 1;
if (map_type != FCELL_TYPE && map_type != DCELL_TYPE) {
- G_warning
- ("G_set_fp_type() can only be called with FCELL_TYPE or DCELL_TYPE");
+ G_warning(_("G_set_fp_type(): can only be called with FCELL_TYPE or DCELL_TYPE"));
return -1;
}
FP_TYPE = map_type;
@@ -893,21 +929,23 @@
/*!
- * \brief
- *
- * Returns true(1) if raster map <em>name</em> in <em>mapset</em>
- * is a floating-point dataset; false(0) otherwise.
- *
- * \param name
- * \param mapset
- * \return int
- */
+ \brief Check if raster map is floating-point
+
+ Returns true (1) if raster map <i>name</i> in <i>mapset</i>
+ is a floating-point dataset; false(0) otherwise.
+
+ \param name map name
+ \param mapset mapset name
+
+ \return 1 floating-point
+ \return 0 int
+*/
int G_raster_map_is_fp(const char *name, const char *mapset)
{
char path[GPATH_MAX];
if (G_find_cell2(name, mapset) == NULL) {
- G_warning(_("unable to find [%s] in [%s]"), name, mapset);
+ G_warning(_("Unable to find <%s@%s>"), name, mapset);
return -1;
}
G__file_name(path, "fcell", name, mapset);
@@ -916,54 +954,50 @@
G__file_name(path, "g3dcell", name, mapset);
if (access(path, 0) == 0)
return 1;
+
return 0;
}
+/*!
+ \brief Determine raster data type
+
+ Determines if the raster map is floating point or integer. Returns
+ DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
+ integer maps, -1 if error has occured
+
+ This function just calls G_raster_map_type()!
+ \param name map name
+ \param mapset mapset where map <i>name</i> lives
-
-/*!
- * \brief Determine raster type
- *
- * Determines if the raster map is floating point or integer. Returns
- * DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
- * integer maps, -1 if error has occured
- *
- * NOTE: If the user specifies a fully qualified raster name which exists,
- * then <i>G_raster_map_type()</i> modifies <b>name</b> by removing the
- * "@<i>mapset</i>". (due to it calling <i>G_find_cell()</i>)
- *
- * \param name
- * \param mapset
- * \return RASTER_MAP_TYPE
- */
+ \return raster data type
+*/
RASTER_MAP_TYPE G_raster_map_type(const char *name, const char *mapset)
{
return G_raster_map_type2(name, mapset);
}
+/*!
+ \brief Determine raster type (look but don't touch)
+ See G_raster_map_type().
-/*!
- * \brief Determine raster type (look but don't touch)
- *
- * Same as G_raster_map_type() but use G_find_cell2() so <b>name</b> is not
- * modified.
- *
- * Determines if the raster map is floating point or integer. Returns
- * DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
- * integer maps, -1 if error has occured
- *
- * \param name
- * \param mapset
- * \return RASTER_MAP_TYPE
- */
+ \param name map name
+ \param mapset mapset where map <i>name</i> lives
+
+ \return raster data type
+*/
RASTER_MAP_TYPE G_raster_map_type2(const char *name, const char *mapset)
{
char path[GPATH_MAX];
if (G_find_cell2(name, mapset) == NULL) {
- G_warning(_("unable to find [%s] in [%s]"), name, mapset);
+ if (mapset) {
+ G_warning(_("Raster map <%s> not found in mapset <%s>"), name, mapset);
+ }
+ else {
+ G_warning(_("Raster map <%s> not found"), name);
+ }
return -1;
}
G__file_name(path, "fcell", name, mapset);
@@ -979,17 +1013,16 @@
return CELL_TYPE;
}
+/*!
+ \brief Determine raster type from descriptor
+
+ Determines if the raster map is floating point or integer. Returns
+ DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
+ integer maps, -1 if error has occured
+
+ \param fd file descriptor
-
-/*!
- * \brief Determine raster type from descriptor
- *
- * Determines if the raster map is floating point or integer. Returns
- * DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
- * integer maps, -1 if error has occured
- *
- * \param fd
- * \return RASTER_MAP_TYPE
+ \return raster data type
*/
RASTER_MAP_TYPE G_get_raster_map_type(int fd)
{
@@ -998,15 +1031,15 @@
return fcb->map_type;
}
+/*!
+ \brief Determines whether the floating points cell file has double or float type
-
+ \param name map name
+ \param mapset mapset where map <i>name</i> lives
+
+ \return raster type (fcell, dcell)
+*/
RASTER_MAP_TYPE G__check_fp_type(const char *name, const char *mapset)
-/* determines whether the flotsing points cell file has double or float type */
-/* returns DCELL_TYPE for double, FCELL_TYPE for float, -1 for error */
-/* f_format file:
- type: float/double
- byte_order: xdr/bytes?
- */
{
char path[GPATH_MAX];
struct Key_Value *format_keys;
@@ -1017,12 +1050,12 @@
G__file_name_misc(path, "cell_misc", FORMAT_FILE, name, mapset);
if (access(path, 0) != 0) {
- G_warning(_("unable to find [%s]"), path);
+ G_warning(_("Unable to find '%s'"), path);
return -1;
}
format_keys = G_read_key_value_file(path, &in_stat);
if (in_stat != 0) {
- G_warning(_("Unable to open %s"), path);
+ G_warning(_("Unable to open '%s'"), path);
return -1;
}
if ((str = G_find_key_value("type", format_keys)) != NULL) {
@@ -1032,7 +1065,8 @@
else if (strcmp(str, "float") == 0)
map_type = FCELL_TYPE;
else {
- G_warning(_("invalid type: field %s in file %s "), str, path);
+ G_warning(_("Invalid type: field '%s' in file '%s'"),
+ str, path);
G_free_key_value(format_keys);
return -1;
}
@@ -1045,13 +1079,34 @@
if ((str1 = G_find_key_value("byte_order", format_keys)) != NULL) {
G_strip(str1);
if (strcmp(str1, "xdr") != 0)
- G_warning("the map %s is not xdr: byte_order: %s", name, str);
+ G_warning(_("Raster map <%s> is not xdr: byte_order: %s"),
+ name, str);
/* here read and translate byte order if not using xdr */
}
G_free_key_value(format_keys);
return map_type;
}
+/*!
+ \brief Opens a new raster map
+
+ Opens a new raster map of type <i>wr_type</i>
+
+ See warnings and notes for G_open_cell_new().
+
+ Supported data types:
+ - CELL_TYPE
+ - FCELL_TYPE
+ - DCELL_TYPE
+
+ On CELL_TYPE calls G_open_cell_new() otherwise G_open_fp_cell_new().
+
+ \param name map name
+ \param wr_type raster data type
+
+ \return nonnegative file descriptor (int)
+ \return -1 on error
+*/
int G_open_raster_new(const char *name, RASTER_MAP_TYPE wr_type)
{
if (wr_type == CELL_TYPE)
@@ -1061,6 +1116,17 @@
return G_open_fp_cell_new(name);
}
+/*!
+ \brief Opens a new raster map (uncompressed)
+
+ See G_open_raster_new().
+
+ \param name map name
+ \param wr_type raster data type
+
+ \return nonnegative file descriptor (int)
+ \return -1 on error
+*/
int G_open_raster_new_uncompressed(const char *name, RASTER_MAP_TYPE wr_type)
{
if (wr_type == CELL_TYPE)
@@ -1070,21 +1136,21 @@
return G_open_fp_cell_new_uncompressed(name);
}
+/*!
+ \brief Sets quant translation rules for raster map opened for
+ reading.
-/*!
- * \brief
- *
- * Sets quant
- * translation rules for raster map opened for reading. fd is a file descriptor
- * returned by G_open_cell_old(). After calling this function,
- * G_get_c_raster_row() and G_get_map_row() will use rules defined by q
- * (instead of using rules defined in map's quant file) to convert floats to
- * ints.
- *
- * \param fd
- * \param q
- * \return int
- */
+ Returned by G_open_cell_old(). After calling this function,
+ G_get_c_raster_row() and G_get_map_row() will use rules defined by q
+ (instead of using rules defined in map's quant file) to convert floats to
+ ints.
+
+ \param fd file descriptor (cell file)
+ \param q pointer to Quant structure
+
+ \return 0 success
+ \return -1 failure
+*/
int G_set_quant_rules(int fd, struct Quant *q)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -1093,8 +1159,8 @@
struct Quant_table *p;
if (fcb->open_mode != OPEN_OLD) {
- G_warning
- ("G_set_quant_rules can be called only for raster maps opened for reading");
+ G_warning(_("G_set_quant_rules() can be called only for "
+ "raster maps opened for reading"));
return -1;
}
/* copy all info from q to fcb->quant) */
More information about the grass-commit
mailing list