Loading...
Searching...
No Matches
timestamp.c File Reference

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

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

Referenced by G_has_raster3d_timestamp(), G_read_raster3d_timestamp(), G_remove_raster3d_timestamp(), and G_write_raster3d_timestamp().

## RAST_MISC

#define RAST_MISC "cell_misc"

Definition at line 87 of file timestamp.c.

Referenced by G_has_raster_timestamp(), G_read_raster_timestamp(), G_remove_raster_timestamp(), and G_write_raster_timestamp().

## 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 datetime_format(), 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 count, and datetime_copy().

## 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 G_debug(), G_file_name(), name, and NULL.

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.

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(), 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(), 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 datetime_copy().

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 datetime_copy().

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(), name, and NULL.