GRASS GIS 8 Programmer's Manual  8.2.2dev(2023)-3d2c704037
timestamp.c File Reference

GIS Library - Timestamp management. More...

#include <string.h>
#include <unistd.h>
#include <grass/gis.h>
#include <grass/vect/dig_defines.h>
#include <grass/glocale.h>
Include dependency graph for timestamp.c:

Go to the source code of this file.

Macros

#define RAST_MISC   "cell_misc"
 
#define GRID3   "grid3"
 

Functions

void G_init_timestamp (struct TimeStamp *ts)
 Initialize timestamp structure. More...
 
void G_set_timestamp (struct TimeStamp *ts, const DateTime *dt)
 Set timestamp (single) More...
 
void G_set_timestamp_range (struct TimeStamp *ts, const DateTime *dt1, const DateTime *dt2)
 Set timestamp (range) More...
 
int G__read_timestamp (FILE *fd, struct TimeStamp *ts)
 Read timestamp. More...
 
int G_write_timestamp (FILE *fd, const struct TimeStamp *ts)
 Output TimeStamp structure to a file as a formatted string. More...
 
int G_format_timestamp (const struct TimeStamp *ts, char *buf)
 Create text string from TimeStamp structure. More...
 
int G_scan_timestamp (struct TimeStamp *ts, const char *buf)
 Fill a TimeStamp structure from a datetime string. More...
 
void G_get_timestamps (const struct TimeStamp *ts, DateTime *dt1, DateTime *dt2, int *count)
 Copy TimeStamp into [two] Datetimes structs. More...
 
int G_has_raster_timestamp (const char *name, const char *mapset)
 Check if timestamp for raster map exists. More...
 
int G_read_raster_timestamp (const char *name, const char *mapset, struct TimeStamp *ts)
 Read timestamp from raster map. More...
 
int G_write_raster_timestamp (const char *name, const struct TimeStamp *ts)
 Write timestamp of raster map. More...
 
int G_remove_raster_timestamp (const char *name)
 Remove timestamp from raster map. More...
 
int G_has_vector_timestamp (const char *name, const char *layer, const char *mapset)
 Check if timestamp for vector map exists. More...
 
int G_read_vector_timestamp (const char *name, const char *layer, const char *mapset, struct TimeStamp *ts)
 Read timestamp from vector map. More...
 
int G_write_vector_timestamp (const char *name, const char *layer, const struct TimeStamp *ts)
 Write timestamp of vector map. More...
 
int G_remove_vector_timestamp (const char *name, const char *layer)
 Remove timestamp from vector map. More...
 
int G_has_raster3d_timestamp (const char *name, const char *mapset)
 Check if timestamp for 3D raster map exists. More...
 
int G_read_raster3d_timestamp (const char *name, const char *mapset, struct TimeStamp *ts)
 Read timestamp from 3D raster map. More...
 
int G_write_raster3d_timestamp (const char *name, const struct TimeStamp *ts)
 Write timestamp of 3D raster map. More...
 
int G_remove_raster3d_timestamp (const char *name)
 Remove timestamp from 3D raster map. More...
 

Detailed Description

GIS Library - Timestamp management.

Provides DateTime functions for timestamp management.

The timestamp values must use the format as described in the GRASS datetime library. The source tree for this library should have a description of the format. For convience, the formats as of Feb, 1996 are reproduced here:

There are two types of datetime values: absolute and relative. Absolute values specify exact dates and/or times. Relative values specify a span of time. Some examples will help clarify:

Absolute

The general format for absolute values is:

day month year [bc] hour:minute:seconds timezone

day is 1-31 month is jan,feb,...,dec year is 4 digit year [bc] if present, indicates dates is BC hour is 0-23 (24 hour clock) mintue is 0-59 second is 0-59.9999 (fractions of second allowed) timezone is +hhmm or -hhmm (eg, -0600)

parts can be missing

1994 [bc] Jan 1994 [bc] 15 jan 1000 [bc] 15 jan 1994 [bc] 10 [+0000] 15 jan 1994 [bc] 10:00 [+0100] 15 jan 1994 [bc] 10:00:23.34 [-0500]

Relative

There are two types of relative datetime values, year- month and day-second.

The formats are:

[-] # years # months [-] # days # hours # minutes # seconds

The words years, months, days, hours, minutes, seconds are literal words, and the # are the numeric values.

Examples:

2 years 5 months 2 years 5 months 100 days 15 hours 25 minutes 35.34 seconds 100 days 25 minutes 1000 hours 35.34 seconds

The following are illegal because it mixes year-month and day-second (because the number of days in a month or in a year vary):

3 months 15 days 3 years 10 days

(C) 2001-2009 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
Michael Shapiro & Bill Brown, CERL
raster3d functions by Michael Pelizzari, LMCO
Soeren Gebbert, vector timestamp implementation update

Definition in file timestamp.c.

Macro Definition Documentation

◆ GRID3

#define GRID3   "grid3"

Definition at line 86 of file timestamp.c.

Referenced by G_has_raster3d_timestamp(), and G_remove_raster3d_timestamp().

◆ RAST_MISC

#define RAST_MISC   "cell_misc"

Definition at line 85 of file timestamp.c.

Referenced by G_has_raster_timestamp(), and G_remove_raster_timestamp().

Function Documentation

◆ G__read_timestamp()

int G__read_timestamp ( FILE *  fd,
struct TimeStamp ts 
)

Read timestamp.

Parameters
fdfile descriptor
[out]tspointer to TimeStamp structure
Returns
-2 EOF
-1 on error
0 on success

Definition at line 134 of file timestamp.c.

Referenced by G_read_vector_timestamp().

◆ G_format_timestamp()

int G_format_timestamp ( const struct TimeStamp ts,
char *  buf 
)

Create text string from TimeStamp structure.

Fills string *buf with info from TimeStamp structure *ts in a pretty way. The TimeStamp struct is defined in gis.h and populated with e.g. G_read_raster_timestamp().

Parameters
tsTimeStamp structure containing time info
bufstring to receive formatted timestamp
Returns
1 on success
-1 error

Definition at line 181 of file timestamp.c.

◆ G_get_timestamps()

void G_get_timestamps ( const struct TimeStamp ts,
DateTime dt1,
DateTime dt2,
int *  count 
)

Copy TimeStamp into [two] Datetimes structs.

Use to copy the TimeStamp information into Datetimes, as the members of struct TimeStamp shouldn't be accessed directly.

  • count=0 means no datetimes were copied
  • count=1 means 1 datetime was copied into dt1
  • count=2 means 2 datetimes were copied
Parameters
tssource TimeStamp structure
[out]dt1first DateTime struct to be filled
[out]dt2second DateTime struct to be filled
[out]countreturn code

Definition at line 258 of file timestamp.c.

◆ G_has_raster3d_timestamp()

int G_has_raster3d_timestamp ( const char *  name,
const char *  mapset 
)

Check if timestamp for 3D raster map exists.

Parameters
namemap name
mapsetmapset name
Returns
1 on success
0 no timestamp present

Definition at line 573 of file timestamp.c.

References G_find_file2_misc(), and GRID3.

◆ G_has_raster_timestamp()

int G_has_raster_timestamp ( const char *  name,
const char *  mapset 
)

Check if timestamp for raster map exists.

Parameters
namemap name
mapsetmapset name
Returns
1 on success
0 no timestamp present

Definition at line 354 of file timestamp.c.

References G_find_file2_misc(), and RAST_MISC.

◆ G_has_vector_timestamp()

int G_has_vector_timestamp ( const char *  name,
const char *  layer,
const char *  mapset 
)

Check if timestamp for vector map exists.

Parameters
namemap name
layerThe layer names, in case of NULL, layer one is assumed
mapsetmapset name
Returns
1 on success
0 no timestamp present

Definition at line 420 of file timestamp.c.

References G_debug(), G_file_name(), G_snprintf(), GNAME_MAX, GPATH_MAX, GV_DIRECTORY, GV_TIMESTAMP_ELEMENT, NULL, and R_OK.

Referenced by G_read_vector_timestamp().

◆ G_init_timestamp()

void G_init_timestamp ( struct TimeStamp ts)

Initialize timestamp structure.

Parameters
tspointer to TimeStamp structure

Definition at line 93 of file timestamp.c.

◆ G_read_raster3d_timestamp()

int G_read_raster3d_timestamp ( const char *  name,
const char *  mapset,
struct TimeStamp ts 
)

Read timestamp from 3D raster map.

Parameters
namemap name
mapsetmapset name
[out]tsTimeStamp struct to populate
Returns
1 on success
0 or negative on error

Definition at line 591 of file timestamp.c.

◆ G_read_raster_timestamp()

int G_read_raster_timestamp ( const char *  name,
const char *  mapset,
struct TimeStamp ts 
)

Read timestamp from raster map.

Parameters
namemap name
mapsetmapset the map lives in
[out]tsTimeStamp struct to populate
Returns
1 on success
0 or negative on error

Definition at line 372 of file timestamp.c.

◆ G_read_vector_timestamp()

int G_read_vector_timestamp ( const char *  name,
const char *  layer,
const char *  mapset,
struct TimeStamp ts 
)

Read timestamp from vector map.

Parameters
namemap name
layerThe layer names, in case of NULL, layer one is assumed
mapsetmapset name
[out]tsTimeStamp struct to populate
Returns
1 on success
0 no timestamp present
-1 Unable to open file
-2 invalid time stamp

Definition at line 455 of file timestamp.c.

References _, G__read_timestamp(), G_debug(), G_fopen_old(), G_has_vector_timestamp(), G_mapset(), G_snprintf(), G_warning(), GNAME_MAX, GPATH_MAX, GV_DIRECTORY, GV_TIMESTAMP_ELEMENT, and NULL.

◆ G_remove_raster3d_timestamp()

int G_remove_raster3d_timestamp ( const char *  name)

Remove timestamp from 3D raster map.

Only timestamp files in current mapset can be removed.

Parameters
namemap name
Returns
0 if no file
1 on success
-1 on failure

Definition at line 624 of file timestamp.c.

References G_remove_misc(), and GRID3.

◆ G_remove_raster_timestamp()

int G_remove_raster_timestamp ( const char *  name)

Remove timestamp from raster map.

Only timestamp files in current mapset can be removed.

Parameters
namemap name
Returns
0 if no file
1 on success
-1 on error

Definition at line 405 of file timestamp.c.

References G_remove_misc(), and RAST_MISC.

◆ G_remove_vector_timestamp()

int G_remove_vector_timestamp ( const char *  name,
const char *  layer 
)

Remove timestamp from vector map.

Only timestamp files in current mapset can be removed.

Parameters
namemap name
layerThe layer names, in case of NULL, layer one is assumed
Returns
0 if no file
1 on success
-1 on failure

Definition at line 550 of file timestamp.c.

References G_remove(), G_snprintf(), GNAME_MAX, GPATH_MAX, GV_DIRECTORY, and GV_TIMESTAMP_ELEMENT.

◆ G_scan_timestamp()

int G_scan_timestamp ( struct TimeStamp ts,
const char *  buf 
)

Fill a TimeStamp structure from a datetime string.

Populate a TimeStamp structure (defined in gis.h) from a text string. Checks to make sure text string is in valid GRASS datetime format.

Parameters
tsTimeStamp structure to be populated
bufstring containing formatted time info
Returns
1 on success
-1 error

Definition at line 215 of file timestamp.c.

◆ G_set_timestamp()

void G_set_timestamp ( struct TimeStamp ts,
const DateTime dt 
)

Set timestamp (single)

Parameters
tspointer to TimeStamp structure
dtpointer to DateTime structure (date/time to be set)

Definition at line 104 of file timestamp.c.

◆ G_set_timestamp_range()

void G_set_timestamp_range ( struct TimeStamp ts,
const DateTime dt1,
const DateTime dt2 
)

Set timestamp (range)

Parameters
tspointer to TimeStamp structure
dt1,dt2pointer to DateTime structures

Definition at line 116 of file timestamp.c.

◆ G_write_raster3d_timestamp()

int G_write_raster3d_timestamp ( const char *  name,
const struct TimeStamp ts 
)

Write timestamp of 3D raster map.

Parameters
namemap name
[out]tsTimeStamp struct to populate
Returns
1 on success
-1 error - can't create timestamp file
-2 error - invalid datetime in ts

Definition at line 608 of file timestamp.c.

◆ G_write_raster_timestamp()

int G_write_raster_timestamp ( const char *  name,
const struct TimeStamp ts 
)

Write timestamp of raster map.

Parameters
namemap name
[out]tsTimeStamp struct to populate
Returns
1 on success
-1 error - can't create timestamp file
-2 error - invalid datetime in ts

Definition at line 389 of file timestamp.c.

◆ G_write_timestamp()

int G_write_timestamp ( FILE *  fd,
const struct TimeStamp ts 
)

Output TimeStamp structure to a file as a formatted string.

A handy fd might be "stdout".

Parameters
[in,out]fdfile descriptor
tspointer to TimeStamp structure
Returns
0 on success
-1 on error

Definition at line 158 of file timestamp.c.

Referenced by G_write_vector_timestamp().

◆ G_write_vector_timestamp()

int G_write_vector_timestamp ( const char *  name,
const char *  layer,
const struct TimeStamp ts 
)

Write timestamp of vector map.

Parameters
namemap name
layerThe layer names, in case of NULL, layer one is assumed
[out]tsTimeStamp struct to populate
Returns
1 on success
-1 error - can't create timestamp file
-2 error - invalid datetime in ts

Definition at line 505 of file timestamp.c.

References _, G_debug(), G_fopen_new(), G_mapset(), G_snprintf(), G_warning(), G_write_timestamp(), GNAME_MAX, GPATH_MAX, GV_DIRECTORY, GV_TIMESTAMP_ELEMENT, and NULL.