[GRASS-SVN] r29642 - grass/trunk/lib/gis
svn_grass at osgeo.org
svn_grass at osgeo.org
Wed Jan 9 15:07:37 EST 2008
Author: martinl
Date: 2008-01-09 15:07:37 -0500 (Wed, 09 Jan 2008)
New Revision: 29642
Modified:
grass/trunk/lib/gis/get_ellipse.c
grass/trunk/lib/gis/key_value1.c
grass/trunk/lib/gis/key_value2.c
grass/trunk/lib/gis/key_value3.c
grass/trunk/lib/gis/key_value4.c
Log:
Doxygen documentation updated
Modified: grass/trunk/lib/gis/get_ellipse.c
===================================================================
--- grass/trunk/lib/gis/get_ellipse.c 2008-01-09 17:44:32 UTC (rev 29641)
+++ grass/trunk/lib/gis/get_ellipse.c 2008-01-09 20:07:37 UTC (rev 29642)
@@ -1,10 +1,32 @@
-#include <grass/gis.h>
-#include <grass/glocale.h>
+/*!
+ \file get_ellipse.c
+
+ \brief Getting ellipsoid parameters from the database.
+
+ This routine returns the ellipsoid parameters from the database.
+ If the PROJECTION_FILE exists in the PERMANENT mapset, read info
+ from that file, otherwise return WGS 84 values.
+
+ Returns: 1 ok, 0 default values used.
+ Dies with diagnostic if there is an error
+
+ (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 CERL
+*/
+
#include <unistd.h>
#include <ctype.h>
#include <string.h>
#include <stdlib.h>
#include <math.h> /* for sqrt() */
+#include <grass/gis.h>
+#include <grass/glocale.h>
static struct table
{
@@ -23,42 +45,20 @@
static int compare_table_names(const void *, const void *);
static int read_ellipsoid_table(int );
-/*
- * This routine returns the ellipsoid parameters from the database.
- * If the PROJECTION_FILE exists in the PERMANENT mapset, read info from
- * that file, otherwise return WGS 84 values.
- *
- * Returns: 1 ok, 0 default values used.
- * Dies with diagnostic if there is an error
- */
-
/*!
* \brief get ellipsoid parameters
*
- * This routine returns the semi-major axis <b>a</b> (in meters)
- * and the eccentricity squared <b>e2</b> for the ellipsoid associated with the
- * database. If there is no ellipsoid explicitly associated with the database, it
- * returns the values for the WGS 84 ellipsoid.
+ * This routine returns the semi-major axis <b>a</b> (in meters) and
+ * the eccentricity squared <b>e2</b> for the ellipsoid associated
+ * with the database. If there is no ellipsoid explicitly associated
+ * with the database, it returns the values for the WGS 84 ellipsoid.
*
- * \param a
- * \param e2
- * \return int
- */
-
-
-/*!
- * \brief get ellipsoid parameters
+ * \param[out] a semi-major axis
+ * \param[out] e2 eccentricity squared
*
- * This routine returns the semi-major axis <b>a</b> (in meters)
- * and the eccentricity squared <b>e2</b> for the ellipsoid associated with the
- * database. If there is no ellipsoid explicitly associated with the database, it
- * returns the values for the WGS 84 ellipsoid.
- *
- * \param a
- * \param e2
- * \return int
+ * \return 1 success
+ * \return 0 default values used
*/
-
int
G_get_ellipsoid_parameters (double *a, double *e2)
{
@@ -70,40 +70,44 @@
proj_keys = NULL;
G__file_name (ipath, "", PROJECTION_FILE, PERMANENT);
+
if (access(ipath,0) !=0)
{
*a = 6378137.0 ;
*e2 = .006694385 ;
return 0;
}
+
proj_keys = G_read_key_value_file(ipath, &in_stat);
+
if (in_stat !=0)
{
- sprintf (err, _("Unable to open file %s in %s"),PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ G_fatal_error (_("Unable to open file %s in <%s>"),
+ PROJECTION_FILE, PERMANENT);
}
+
if ((str = G_find_key_value("ellps",proj_keys))!=NULL) {
if (strncmp(str,"sphere",6)==0) {
str = G_find_key_value("a",proj_keys);
if (str!=NULL) {
if(sscanf(str,"%lf",a)!=1) {
- sprintf (err, _("invalid a: field %s in file %s in %s")
- ,str,PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ sprintf (err, );
+ G_fatal_error (_("Invalid a: field '%s' in file %s in <%s>"),
+ str, PROJECTION_FILE, PERMANENT);
}
}
else {
*a = 6370997.0 ;
}
*e2 = 0.0 ;
+
G_free_key_value(proj_keys);
return 0;
}
else {
if (G_get_ellipsoid_by_name (str, a, e2)==0) {
- sprintf (err, _("invalid ellipsoid %s in file %s in %s")
- ,str,PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ G_fatal_error (_("Invalid ellipsoid '%s' in file %s in <%s>"),
+ str, PROJECTION_FILE, PERMANENT);
}
else {
G_free_key_value(proj_keys);
@@ -116,15 +120,14 @@
str1 = G_find_key_value("es",proj_keys);
if ((str!=NULL) && (str1!=NULL)) {
if(sscanf(str,"%lf",a)!=1) {
- sprintf (err, _("invalid a: field %s in file %s in %s")
- ,str,PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ G_fatal_error (_("Invalid a: field '%s' in file %s in <%s>"),
+ str, PROJECTION_FILE, PERMANENT);
}
if(sscanf(str1,"%lf",e2)!=1) {
- sprintf (err, _("invalid es: field %s in file %s in %s")
- ,str,PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ G_fatal_error(_("Invalid es: field '%s' in file %s in <%s>"),
+ str,PROJECTION_FILE,PERMANENT);
}
+
G_free_key_value(proj_keys);
return 1;
}
@@ -137,9 +140,8 @@
return 0;
}
else {
- sprintf (err, _("No ellipsoid info given in file %s in %s"),
- PROJECTION_FILE,PERMANENT);
- G_fatal_error (err);
+ G_fatal_error(_("No ellipsoid info given in file %s in <%s>"),
+ PROJECTION_FILE,PERMANENT);
}
}
}
@@ -151,42 +153,20 @@
return 0;
}
-/*
- * looks up ellipsoid in ellipsoid table and returns the
- * a, e2 parameters for the ellipsoid
- *
- * returns 1 if ok,
- * 0 if not found in table
- */
-
-
/*!
- * \brief get ellipsoid by name
- *
- * This routine returns the semi-major axis <b>a</b> (in
- * meters) and eccentricity squared <b>e2</b> for the named ellipsoid. Returns
- * 1 if <b>name</b> is a known ellipsoid, 0 otherwise.
- *
- * \param name
- * \param a
- * \param e2
- * \return int
- */
-
-
-/*!
* \brief get ellipsoid parameters by name
*
- * This routine returns the semi-major axis <b>a</b> (in
- * meters) and eccentricity squared <b>e2</b> for the named ellipsoid. Returns
- * 1 if <b>name</b> is a known ellipsoid, 0 otherwise.
+ * This routine returns the semi-major axis <b>a</b> (in meters) and
+ * eccentricity squared <b>e2</b> for the named ellipsoid. Returns 1
+ * if <b>name</b> is a known ellipsoid, 0 otherwise.
*
- * \param name
- * \param a
- * \param e2
- * \return int
+ * \param[in] name ellipsoid name
+ * \param[out] a semi-major axis
+ * \param[out] e2 eccentricity squared
+ *
+ * \return 1 on success
+ * \return 0 if ellipsoid not found
*/
-
int
G_get_ellipsoid_by_name (const char *name, double *a, double *e2)
{
@@ -206,63 +186,18 @@
return 0;
}
-/*
- * returns name(s) of ellipsoid
- *
- * for (i = 0; name = G_ellipsoid_name(i); i++)
- * ....
- */
-
/*!
- * \brief return ellopsoid name
+ * \brief get ellipsoid name
*
- * This routine
- * returns a pointer to a string containg the name for the <b>n</b><i>th</i>
- * ellipsoid in the GRASS ellipsoid table; NULL when <b>n</b> is too large. It
- * can be used as follows:
- \code
- int n ;
- char *name ;
- for ( n=0 ; name=G_ellipsoid_name(n) ; n++ )
- fprintf(stdout, "%s\n", name);
- \endcode
+ * This function returns a pointer to the short name for the
+ * <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less than 0 or greater
+ * than the number of known ellipsoids, it returns a NULL pointer.
*
- * \param n
- * \return char *
- */
-
-
-/*!
- * \brief return ellopsoid name
+ * \param[in] n ellipsoid identificator
*
- * This routine
- * returns a pointer to a string containg the name for the <b>n</b><i>th</i>
- * ellipsoid in the GRASS ellipsoid table; NULL when <b>n</b> is below zero or
- * too large. It can be used as follows:
- \code
- int n ;
- char *name ;
- for ( n=0 ; name=G_ellipsoid_name(n) ; n++ )
- fprintf(stdout, "%s\n", name);
- \endcode
- *
- * \param n
- * \return char *
+ * \return char * ellipsoid name
+ * \return NULL if no ellipsoid found
*/
-
-
-/*!
- * \brief get ellipsoid name
- *
- * This function
- * returns a pointer to the short name for the <b>n</b><i>th</i> ellipsoid.
- * If <b>n</b> is less than 0 or greater than the number of known ellipsoids,
- * it returns a NULL pointer.
- *
- * \param n
- * \return char *
- */
-
char *
G_ellipsoid_name (int n)
{
@@ -284,18 +219,19 @@
/*!
* \brief get spheroid parameters by name
*
- * This function returns the
- * semi-major axis <b>a</b> (in meters), the eccentricity squared <b>e2</b>
- * and the inverse flattening <b>f</b> for the named ellipsoid. Returns 1 if
- * <b>name</b> is a known ellipsoid, 0 otherwise.
+ * This function returns the semi-major axis <b>a</b> (in meters), the
+ * eccentricity squared <b>e2</b> and the inverse flattening <b>f</b>
+ * for the named ellipsoid. Returns 1 if <b>name</b> is a known
+ * ellipsoid, 0 otherwise.
*
- * \param name
- * \param a
- * \param e2
- * \param f
- * \return int
+ * \param[in] name spheroid name
+ * \param[out] a semi-major axis
+ * \param[out] e2 eccentricity squared
+ * \param[out] f inverse flattening
+ *
+ * \return 1 on success
+ * \return 0 if no spheroid found
*/
-
int
G_get_spheroid_by_name(const char *name, double *a, double *e2, double *f)
{
@@ -320,13 +256,14 @@
/*!
* \brief get description for <b>n</b><i>th</i> ellipsoid
*
- * This function returns a pointer to the
- * description text for the <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less
- * than 0 or greater than the number of known ellipsoids, it returns a NULL
- * pointer.
+ * This function returns a pointer to the description text for the
+ * <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less than 0 or greater
+ * than the number of known ellipsoids, it returns a NULL pointer.
*
- * \param n
- * \return char *
+ * \param[in] n ellipsoid identificator
+ *
+ * \return pointer to ellipsoid description
+ * \return NULL if no ellipsoid found
*/
char *
@@ -414,7 +351,7 @@
if (fd == NULL)
{
perror (file);
- sprintf (buf, _("unable to open ellipsoid table file: %s"), file);
+ sprintf (buf, _("Unable to open ellipsoid table file <%s>"), file);
fatal ? G_fatal_error(buf) : G_warning (buf);
return 0;
}
Modified: grass/trunk/lib/gis/key_value1.c
===================================================================
--- grass/trunk/lib/gis/key_value1.c 2008-01-09 17:44:32 UTC (rev 29641)
+++ grass/trunk/lib/gis/key_value1.c 2008-01-09 20:07:37 UTC (rev 29642)
@@ -1,3 +1,18 @@
+/*!
+ \file key_value1.c
+
+ \brief Key_Value management.
+
+ (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 CERL
+*/
+
#include <string.h>
#include <stdlib.h>
#include <grass/gis.h>
@@ -2,2 +17,7 @@
+/*!
+ \brief Allocate and initialize Key_Value structure
+
+ \return poiter to allocated Key_Value structure
+*/
struct Key_Value *
@@ -19,12 +39,20 @@
return kv;
}
-/* if key has spaces in it, this will break the logic
- * so rule is: NO SPACES IN key
- * returns 0 - no memory
- * 1 - ok, but key was NULL or "" so ignored
- * 2 - ok
- */
+/*!
+ \brief Set value for given key
+
+ If key has spaces in it, this will break the logic
+ so rule is: NO SPACES IN key.
+
+ \param[in] key key to be set up
+ \param[in] value value for given key
+ \param[in,out] kv Key_value structure to be modified
+
+ \return 0 no memory
+ \return 1 ok, but key was NULL or "" so ignored
+ \return 2 ok
+*/
int G_set_key_value (
const char *key, const char *value,
struct Key_Value *kv)
@@ -99,6 +127,15 @@
return 2;
}
+/*!
+ \brief Find given key
+
+ \param[in] key key to be found
+ \param[in] kv Key_value structure
+
+ \return poiter to value of key
+ \return NULL if no key found
+*/
char *G_find_key_value (const char *key, const struct Key_Value *kv)
{
int n;
@@ -109,6 +146,13 @@
return NULL;
}
+/*!
+ \brief Free allocated Key_Value structure
+
+ \param[in] kv Key_Value structure
+
+ \return 0
+*/
int G_free_key_value(struct Key_Value *kv)
{
int n;
Modified: grass/trunk/lib/gis/key_value2.c
===================================================================
--- grass/trunk/lib/gis/key_value2.c 2008-01-09 17:44:32 UTC (rev 29641)
+++ grass/trunk/lib/gis/key_value2.c 2008-01-09 20:07:37 UTC (rev 29642)
@@ -1,9 +1,29 @@
+/*!
+ \file key_value2.c
+
+ \brief Read/write Key_Value from/to file.
+
+ (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 CERL
+*/
+
#include <grass/gis.h>
-/* returns 0, ok
- * -1 error writing
- */
+/*!
+ \brief Write key/value pairs to file
+ \param[in,out] fd file to write to
+ \param[in] kv Key_Value structure
+
+ \return 0 success
+ \return -1 error writing
+*/
int G_fwrite_key_value (
FILE *fd,
const struct Key_Value *kv)
@@ -21,6 +41,16 @@
return err;
}
+/*!
+ \brief Read key/values pairs from file
+
+ Allocated memory must be freed G_free_key_value().
+
+ \param[in] fd file to read key/values from
+
+ \return pointer to allocated Key_Value structure
+ \return NULL on error
+*/
struct Key_Value *
G_fread_key_value (FILE *fd)
Modified: grass/trunk/lib/gis/key_value3.c
===================================================================
--- grass/trunk/lib/gis/key_value3.c 2008-01-09 17:44:32 UTC (rev 29641)
+++ grass/trunk/lib/gis/key_value3.c 2008-01-09 20:07:37 UTC (rev 29642)
@@ -1,5 +1,31 @@
+/*!
+ \file key_value3.c
+
+ \brief Key_Value management.
+
+ (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 CERL
+*/
+
#include <grass/gis.h>
+/*!
+ \brief Write key/value pairs to file
+
+ \param[in] file filename for writing
+ \param[in] kv Key_Value structure
+ \param[out] stat status (0 ok, -3 cannot open file, -4 error writing key/value)
+
+ \return 0 success
+ \return 1 error writing
+*/
+
int G_write_key_value_file (
const char *file,
const struct Key_Value *kv,
@@ -16,6 +42,17 @@
return (*stat != 0);
}
+/*!
+ \brief Read key/values pairs from file
+
+ Allocated memory must be freed G_free_key_value().
+
+ \param[in] file filename for reading
+ \param[out] stat status (0 ok, -1 cannot open file, -2 error writing key/value)
+
+ \return poiter to allocated Key_Value structure
+ \return NULL on error
+*/
struct Key_Value *G_read_key_value_file(const char *file, int *stat)
{
FILE *fd;
Modified: grass/trunk/lib/gis/key_value4.c
===================================================================
--- grass/trunk/lib/gis/key_value4.c 2008-01-09 17:44:32 UTC (rev 29641)
+++ grass/trunk/lib/gis/key_value4.c 2008-01-09 20:07:37 UTC (rev 29642)
@@ -1,11 +1,33 @@
+/*!
+ \file key_value4.c
+
+ \brief Key_Value management.
+
+ (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 CERL
+*/
+
#include <grass/gis.h>
#include <string.h>
-/* -1 can't open file for reading
- * -2 no memory for key,value info, file not modified
- * -3 can't open file for re-write
- * -4 error writing the file (might be damaged)
- */
+/*!
+ \brief Update file, set up value for given key
+
+ \param[in] file filename to be updated
+ \param[in] key key value
+ \param[in] value value to be updated
+
+ \return -1 can't open file for reading
+ \return -2 no memory for key,value info, file not modified
+ \return -3 can't open file for re-write
+ \return -4 error writing the file (might be damaged)
+*/
int G_update_key_value_file (const char *file, const char *key, const char *value)
{
struct Key_Value *kv;
@@ -27,10 +49,18 @@
return stat;
}
-/* returns: <0 are file/memory errors
- * 0 not found
- * 1 ok
- */
+/*!
+ \brief Look up for key in file
+
+ \param[in] file filename
+ \param[in] key key to be found in file
+ \param[out] value value for key
+ \param[in] n number of characters to be copied
+
+ \return <0 are file/memory errors
+ \return 0 not found
+ \return 1 ok
+*/
int G_lookup_key_value_from_file(
const char *file,
const char *key,
More information about the grass-commit
mailing list