GIS Library - Timestamp management. More...

#include <stdio.h>
#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.

void	G_set_timestamp (struct TimeStamp ts, const DateTime dt)
	Set timestamp (single)

void	G_set_timestamp_range (struct TimeStamp ts, const DateTime dt1, const DateTime *dt2)
	Set timestamp (range)

int	G__read_timestamp (FILE fd, struct TimeStamp ts)
	Read timestamp.

int	G_write_timestamp (FILE fd, const struct TimeStamp ts)
	Output TimeStamp structure to a file as a formatted string.

int	G_format_timestamp (const struct TimeStamp ts, char buf)
	Create text string from TimeStamp structure.

int	G_scan_timestamp (struct TimeStamp ts, const char buf)
	Fill a TimeStamp structure from a datetime string.

void	G_get_timestamps (const struct TimeStamp ts, DateTime dt1, DateTime dt2, int count)
	Copy TimeStamp into [two] Datetimes structs.

int	G_has_raster_timestamp (const char name, const char mapset)
	Check if timestamp for raster map exists.

int	G_read_raster_timestamp (const char name, const char mapset, struct TimeStamp *ts)
	Read timestamp from raster map.

int	G_write_raster_timestamp (const char name, const struct TimeStamp ts)
	Write timestamp of raster map.

int	G_remove_raster_timestamp (const char *name)
	Remove timestamp from raster map.

int	G_has_vector_timestamp (const char name, const char layer, const char *mapset)
	Check if timestamp for vector map exists.

int	G_read_vector_timestamp (const char name, const char layer, const char mapset, struct TimeStamp ts)
	Read timestamp from vector map.

int	G_write_vector_timestamp (const char name, const char layer, const struct TimeStamp *ts)
	Write timestamp of vector map.

int	G_remove_vector_timestamp (const char name, const char layer)
	Remove timestamp from vector map.

int	G_has_raster3d_timestamp (const char name, const char mapset)
	Check if timestamp for 3D raster map exists.

int	G_read_raster3d_timestamp (const char name, const char mapset, struct TimeStamp *ts)
	Read timestamp from 3D raster map.

int	G_write_raster3d_timestamp (const char name, const struct TimeStamp ts)
	Write timestamp of 3D raster map.

int	G_remove_raster3d_timestamp (const char *name)
	Remove timestamp from 3D raster map.

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 convenience, 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) minute 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

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 88 of file timestamp.c.

◆ RAST_MISC

#define RAST_MISC "cell_misc"

Definition at line 87 of file timestamp.c.

Function Documentation

◆ G__read_timestamp()

int G__read_timestamp	(	FILE *	fd,
		struct TimeStamp *	ts
	)

Read timestamp.

Parameters

	fd	file descriptor
[out]	ts	pointer to TimeStamp structure

Returns: -2 EOF; -1 on error; 0 on success

Definition at line 136 of file timestamp.c.

References G_scan_timestamp().

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

ts	TimeStamp structure containing time info
buf	string to receive formatted timestamp

Returns: 1 on success; -1 error

Definition at line 183 of file timestamp.c.

References TimeStamp::count, datetime_format(), TimeStamp::dt, and strcpy.

Referenced by G_write_timestamp().

◆ 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

	ts	source TimeStamp structure
[out]	dt1	first DateTime struct to be filled
[out]	dt2	second DateTime struct to be filled
[out]	count	return code

Definition at line 260 of file timestamp.c.

References TimeStamp::count, count, datetime_copy(), and TimeStamp::dt.

◆ G_has_raster3d_timestamp()

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

Check if timestamp for 3D raster map exists.

Parameters

name	map name
mapset	mapset name

Returns: 1 on success; 0 no timestamp present

Definition at line 576 of file timestamp.c.

References G_find_file2_misc(), GRID3, and name.

◆ G_has_raster_timestamp()

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

Check if timestamp for raster map exists.

Parameters

name	map name
mapset	mapset name

Returns: 1 on success; 0 no timestamp present

Definition at line 356 of file timestamp.c.

References G_find_file2_misc(), name, 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

name	map name
layer	The layer names, in case of NULL, layer one is assumed
mapset	mapset name

Returns: 1 on success; 0 no timestamp present

Definition at line 422 of file timestamp.c.

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

Referenced by G_read_vector_timestamp().

◆ G_init_timestamp()

void G_init_timestamp ( struct TimeStamp * ts )

Initialize timestamp structure.

Parameters

ts	pointer to TimeStamp structure

Definition at line 95 of file timestamp.c.

References TimeStamp::count.

Referenced by G_scan_timestamp().

◆ 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

	name	map name
	mapset	mapset name
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; 0 or negative on error

Definition at line 594 of file timestamp.c.

References GRID3, and name.

◆ G_read_raster_timestamp()

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

Read timestamp from raster map.

Parameters

	name	map name
	mapset	mapset the map lives in
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; 0 or negative on error

Definition at line 374 of file timestamp.c.

References name, and RAST_MISC.

◆ 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

	name	map name
	layer	The layer names, in case of NULL, layer one is assumed
	mapset	mapset name
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; 0 no timestamp present; -1 Unable to open file; -2 invalid time stamp

Definition at line 458 of file timestamp.c.

References _, G__read_timestamp(), G_debug(), G_fopen_old(), G_has_vector_timestamp(), G_mapset(), G_warning(), GNAME_MAX, GPATH_MAX, GV_DIRECTORY, GV_TIMESTAMP_ELEMENT, name, 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

name map name

Returns: 0 if no file; 1 on success; -1 on failure

Definition at line 627 of file timestamp.c.

References G_remove_misc(), GRID3, and name.

◆ 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

name map name

Returns: 0 if no file; 1 on success; -1 on error

Definition at line 407 of file timestamp.c.

References G_remove_misc(), name, 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

name	map name
layer	The layer names, in case of NULL, layer one is assumed

Returns: 0 if no file; 1 on success; -1 on failure

Definition at line 553 of file timestamp.c.

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

◆ 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

ts	TimeStamp structure to be populated
buf	string containing formatted time info

Returns: 1 on success; -1 error

Definition at line 217 of file timestamp.c.

References datetime_scan(), G_init_timestamp(), G_set_timestamp(), G_set_timestamp_range(), and t.

Referenced by G__read_timestamp().

◆ G_set_timestamp()

void G_set_timestamp	(	struct TimeStamp *	ts,
		const DateTime *	dt
	)

Set timestamp (single)

Parameters

ts	pointer to TimeStamp structure
dt	pointer to DateTime structure (date/time to be set)

Definition at line 106 of file timestamp.c.

References TimeStamp::count, datetime_copy(), and TimeStamp::dt.

Referenced by G_scan_timestamp().

◆ G_set_timestamp_range()

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

Set timestamp (range)

Parameters

ts	pointer to TimeStamp structure
dt1,dt2	pointer to DateTime structures

Definition at line 118 of file timestamp.c.

References TimeStamp::count, datetime_copy(), and TimeStamp::dt.

Referenced by G_scan_timestamp().

◆ G_write_raster3d_timestamp()

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

Write timestamp of 3D raster map.

Parameters

	name	map name
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; -1 error - can't create timestamp file; -2 error - invalid datetime in ts

Definition at line 611 of file timestamp.c.

References GRID3, and name.

◆ G_write_raster_timestamp()

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

Write timestamp of raster map.

Parameters

	name	map name
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; -1 error - can't create timestamp file; -2 error - invalid datetime in ts

Definition at line 391 of file timestamp.c.

References name, and RAST_MISC.

Referenced by IL_output_2d().

◆ 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]	fd	file descriptor
	ts	pointer to TimeStamp structure

Returns: 0 on success; -1 on error

Definition at line 160 of file timestamp.c.

References G_format_timestamp().

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

	name	map name
	layer	The layer names, in case of NULL, layer one is assumed
[out]	ts	TimeStamp struct to populate

Returns: 1 on success; -1 error - can't create timestamp file; -2 error - invalid datetime in ts

Definition at line 507 of file timestamp.c.

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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ GRID3

◆ RAST_MISC

Function Documentation

◆ G__read_timestamp()

◆ G_format_timestamp()

◆ G_get_timestamps()

◆ G_has_raster3d_timestamp()

◆ G_has_raster_timestamp()

◆ G_has_vector_timestamp()

◆ G_init_timestamp()

◆ G_read_raster3d_timestamp()

◆ G_read_raster_timestamp()

◆ G_read_vector_timestamp()

◆ G_remove_raster3d_timestamp()

◆ G_remove_raster_timestamp()

◆ G_remove_vector_timestamp()

◆ G_scan_timestamp()

◆ G_set_timestamp()

◆ G_set_timestamp_range()

◆ G_write_raster3d_timestamp()

◆ G_write_raster_timestamp()

◆ G_write_timestamp()

◆ G_write_vector_timestamp()