GRASS GIS 7 Programmer's Manual  7.9.dev(2021)-e5379bbd7
history.c File Reference

Raster Library - History management. More...

#include <stdarg.h>
#include <string.h>
#include <grass/gis.h>
#include <grass/raster.h>
#include <grass/glocale.h>
Include dependency graph for history.c:

Go to the source code of this file.

Functions

void Rast_append_history (struct History *hist, const char *str)
 Append a string to a History structure. More...
 
void Rast_append_format_history (struct History *hist, const char *fmt,...)
 Append a formatted string to a History structure. More...
 
int Rast__read_history (struct History *hist, FILE *fp)
 
int Rast_read_history (const char *name, const char *mapset, struct History *hist)
 Read raster history file. More...
 
void Rast__write_history (struct History *hist, FILE *fp)
 
void Rast_write_history (const char *name, struct History *hist)
 Write raster history file. More...
 
const char * Rast_get_history (struct History *hist, int field)
 Set the string of a specific history field. More...
 
void Rast_set_history (struct History *hist, int field, const char *str)
 Set the string of a specific history field. More...
 
void Rast_format_history (struct History *hist, int field, const char *fmt,...)
 
void Rast_short_history (const char *name, const char *type, struct History *hist)
 Initialize history structure. More...
 
int Rast_command_history (struct History *hist)
 Save command line to raster history structure. More...
 
void Rast_clear_history (struct History *hist)
 
void Rast_free_history (struct History *hist)
 
int Rast_history_length (struct History *hist)
 
const char * Rast_history_line (struct History *hist, int line)
 

Detailed Description

Raster Library - History management.

(C) 2001-2009 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

Definition in file history.c.

Function Documentation

◆ Rast__read_history()

int Rast__read_history ( struct History hist,
FILE *  fp 
)

◆ Rast__write_history()

void Rast__write_history ( struct History hist,
FILE *  fp 
)

Definition at line 128 of file history.c.

References History::fields, HIST_NUM_FIELDS, History::lines, and History::nlines.

Referenced by Rast3d_write_history(), and Rast_write_history().

◆ Rast_append_format_history()

void Rast_append_format_history ( struct History hist,
const char *  fmt,
  ... 
)

Append a formatted string to a History structure.

Parameters
histpointer to History structure which holds history info
fmta string of format characters
...the arguments associated with the format characters
Returns
void

Definition at line 45 of file history.c.

References G_realloc, G_vasprintf(), History::lines, and History::nlines.

◆ Rast_append_history()

void Rast_append_history ( struct History hist,
const char *  str 
)

Append a string to a History structure.

Parameters
histpointer to History structure which holds history info
strstring to append
Returns
void

Definition at line 29 of file history.c.

References G_realloc, G_store(), History::lines, and History::nlines.

Referenced by Rast__read_history(), and Rast_command_history().

◆ Rast_clear_history()

void Rast_clear_history ( struct History hist)

Definition at line 303 of file history.c.

References G_free(), History::lines, History::nlines, and NULL.

Referenced by Rast_free_history().

◆ Rast_command_history()

int Rast_command_history ( struct History hist)

Save command line to raster history structure.

This routine takes an existing (run Rast_short_history first() history structure and adds the command line to the end of the comments array, as cleaned & expanded by the parser.

  • First version had for loops of [i][j] character assignments and ending nulls, but using the string libraries is cleaner and less bug prone.
  • Second version had white space detection, intelligent wrapping, and indentation of continued lines, but this proved a pain in the neck for things like r.patch which can have long strings without any parser-acceptable breaks.
  • This is MK-III, simplified, but that's good: it's cut & paste-able.

Note: use Rast_write_history() to write the structure.

Sample Usage:

struct History history;
Rast_short_history(rasterfile, "raster", &history);
Rast_write_history(rasterfile, &history);
Parameters
histpointer to History structure which holds history info
Returns
0 on success
1 on failure (history file full, no change)
2 on failure (history file full, added as much as we could)

Definition at line 272 of file history.c.

References G_free(), G_recreate_command(), History::nlines, and Rast_append_history().

◆ Rast_format_history()

void Rast_format_history ( struct History hist,
int  field,
const char *  fmt,
  ... 
)

Definition at line 199 of file history.c.

References History::fields, G_free(), and G_vasprintf().

◆ Rast_free_history()

void Rast_free_history ( struct History hist)

Definition at line 317 of file history.c.

References History::fields, G_free(), HIST_NUM_FIELDS, NULL, and Rast_clear_history().

◆ Rast_get_history()

const char* Rast_get_history ( struct History hist,
int  field 
)

Set the string of a specific history field.

Parameters
histpointer to History structure which holds history info
fieldnumber of a specific history field, should be accessed with macros (HIST_MAPID, ...)
Returns
string of the history field

Definition at line 177 of file history.c.

References History::fields.

◆ Rast_history_length()

int Rast_history_length ( struct History hist)

Definition at line 330 of file history.c.

References History::nlines.

◆ Rast_history_line()

const char* Rast_history_line ( struct History hist,
int  line 
)

Definition at line 335 of file history.c.

◆ Rast_read_history()

int Rast_read_history ( const char *  name,
const char *  mapset,
struct History hist 
)

Read raster history file.

This routine reads the history file for the raster map name in mapset into the hist structure.

A diagnostic message is printed and -1 is returned if there is an error reading the history file. Otherwise, 0 is returned.

Parameters
namemap name
mapsetmapset name
histpointer to History structure which holds history info
Returns
-1 on error
0 on success

Definition at line 106 of file history.c.

References _, G_fopen_old(), G_warning(), G_zero(), and Rast__read_history().

◆ Rast_set_history()

void Rast_set_history ( struct History hist,
int  field,
const char *  str 
)

Set the string of a specific history field.

Parameters
histpointer to History structure which holds history info
fieldnumber of a specific history field, should be accessed with macros (HIST_MAPID, ...)
strstring of the history field
Returns
void

Definition at line 192 of file history.c.

References History::fields, G_free(), G_store(), and NULL.

◆ Rast_short_history()

void Rast_short_history ( const char *  name,
const char *  type,
struct History hist 
)

Initialize history structure.

This routine initializes the hist structure, recording the date, user, module name and the raster map name structure. The type can be "raster", "reclass", "GDAL-link", or "virtual".

Note: This routine only initializes the data structure. It does not write the history file.

Parameters
namemap name
typemap type
histpointer to History structure which holds history info

Definition at line 226 of file history.c.

◆ Rast_write_history()

void Rast_write_history ( const char *  name,
struct History hist 
)

Write raster history file.

This routine writes the history file for the raster map name in the current mapset from the hist structure.

A diagnostic message is printed and -1 is returned if there is an error writing the history file. Otherwise, 0 is returned.

Note: The hist structure should first be initialized using Rast_short_history().

Parameters
namemap name
[out]histpointer to History structure which holds history info
Returns
void

Definition at line 158 of file history.c.

References _, G_fatal_error(), G_fopen_new(), and Rast__write_history().