NAME
RuseAs - set the cell representation the application will use
SYNOPSIS
#include "csf.h"
int RuseAs
(
MAP *m,
CSF_CR useType
);
PARAMETERS
-
MAP *m
-
map handle
-
CSF_CR useType
-
CR_UINT1,CR_INT4, CR_REAL4, CR_REAL8, VS_BOOLEAN or VS_LDD
Possible values for a
CSF_CR
are as follows:
* preferred version 2 cell representations
- CR_UINT1 - Boolean, ldd and small nominal and small ordinal.
- CR_INT4 - Large nominal and large ordinal.
- CR_REAL4 - Single scalar and single directional.
* other version 2 cell representations
- CR_REAL8 - Double scalar or directional, and also the only type that
can hold all
cell representation without loss of precision.
* version 1 cell representations
these can be returned by BUT NOT passed to a csf2 function
- CR_INT1 -
.
- CR_INT2 -
.
- CR_UINT2 -
.
- CR_UINT4 -
.
* this one CANNOT be returned by NOR passed to a csf2 function
- CR_UNDEFINED - Just some value different from the rest.
DESCRIPTION
RuseAs enables an application to use cell values
in a different format than they are stored in the map.
Cell values are converted when getting (Rget*-functions) and
putting (Rput*-functions) cells if necessary.
Thus no conversions are applied if cell representation and/or
value scale already match.
Any conversions between the version 2 cell representations,
(CR_UINT1, CR_INT4, CR_REAL4 and CR_REAL8) is possible.
Conversion from a non version 2 cell representation to a version
2 cell representation is only possible when you don't
have write access to the cells.
Conversion rules are exactly as described in K&R 2nd edition section A6.
Two special conversions are possible if you don't
have write access to the cells or if the in-file cell representation is
UINT1:
(1) VS_BOOLEAN: successive calls to the Rget*-functions returns the result of
value != 0
, that is 0 or 1 in UINT1 format. The in-file cell representation can be
anything, except if the value scale is VS_DIRECTION or VS_LDD.
(2) VS_LDD: successive calls to the Rget*-functions returns the result of
value % 10
, that is 1 to 9 in UINT1 format (0's are set to MV_UINT1).
The in-file cell representation must be CR_UINT1 or CR_INT2 and
the value scale must be VS_LDD, VS_CLASSIFIED or VS_NOTDETERMINED.
RETURNS
0 if conversion obeys rules given here. 1 if not (conversions
will not take place).
NOTE
that you must use Rmalloc() to get enough space for both the in-file and
app cell representation.
MERRNO
CANT_USE_AS_BOOLEAN CANT_USE_WRITE_BOOLEAN
CANT_USE_WRITE_LDD
CANT_USE_AS_LDD
CANT_USE_WRITE_OLDCR
ILLEGAL_USE_TYPE
EXAMPLE
#include
#include
#include "csf.h"
/* a simple csf-mask to stdout
* program, with minimal checking
* a mask is boolean-map, here we
* use version 1 compatibility.
*/
void main(int argc, char *argv[] )
{
UINT1 *row;
MAP *map;
size_t r,c;
if (argc != 2)
{
fprintf(stderr,"%s: no file specified\n",argv[0]);
exit(1);
}
map = Mopen(argv[1], M_READ);
if (! RvalueScaleIs(map, VS_BOOLEAN))
{ /* it's not VS_BOOLEAN, VS_CLASSIFIED
* or VS_NOTDETERMINED
*/
fprintf(stderr,"'%s' is not a boolean map\n",argv[1]);
exit(1);
}
RuseAs(map, VS_BOOLEAN);
row = (UINT1 *)Rmalloc(map, RgetNrCols(map));
for(r=0; r < RgetNrRows(map); r++)
{
RgetRow(map, r, row);
for(c=0; c < RgetNrCols(map); c++)
printf("%d ",(int)row[c]);
printf("\n");
}
free(row);
Mclose(map);
exit(0);
}