NCL data types overview

Basic numeric types

In NCL, basic data types are all of the standard types found in nearly all programming languages. Types classified as numeric types support all of the algebraic functions available in NCL (see Expressions). The following is a list of the basic numeric types currently supported; they are listed by their keywords, default size for most systems, and valid numerical ranges:

CAUTION: Currently, arithmetic overflow and underflow are not reported as errors to the user. Assignment of out-of-range values may cause errors.

	double		64bits		+/- ( 2.22507e-308 ) to (8.98846e+307)
	float		32bits		+/- ( 1.175494e-38 ) to (1.701411e+38)
	long		32bits		+/- ( 2.147483e+09 )
	integer		32bits		+/- ( 2.147483e+09 )
	short		16bits		+/- ( 32767 ) 
	byte		8bits		( 0 ) - ( 255 )

Non-numeric types

Non-numeric types are types for which there is no numeric value and that cannot be coerced into a numeric type. Also, in general, non-numeric types only support the .ne. and .eq. operations, with the exception of the string and logical types. Strings use the '+' operation to concatenate one or more strings. The logical type supports .and., .or., .not., and .xor.. The logical types can have three values: the keywords True and False or a missing value.

The graphic type is a reference to an instance of an HLU object. The file type is a reference to a file in a supported file format. The logical type is generated from relational expressions. Logical values are either True or False. Graphic values are returned by the create statement, HLU functions or the getvalues statement, and file values are returned by the addfile intrinsic function.

	string		N/A
	character	8bits
	graphic		N/A
	file		N/A
	logical		N/A

Coercion of types

Coercion is basically the implicit conversion of data from one data type to another. This occurs when two values of different types are operands to the same operator. Operands must be of a compatible type to perform the requested operation. For example, when a float value is multiplied by an integer value, the integer value can easily, without losing or corrupting the value, be converted to a float value. Because there is no loss of information, NCL does this automatically. The following table lists the automatic conversion possibilities for all of the basic types. The data types on the left side can automatically be converted to values of the types on the right side. If a coercion to a common type doesn't exist for both sides of an expression, then a type mismatch error is generated and the script will exit.

Coercion is discussed again in the section of this document covering expressions.

One very important item, which is covered in the functions and the procedures sections, has to do with how parameters work in functions and procedures. First, parameters in NCL are pass-by-reference, meaning that a change to the value of a parameter inside a function changes the value of a variable passed in to the function or procedure. This is important because when a parameter is expected to be a certain type, say float, and an integer variable is passed as the parameter, the integer parameter must be coerced to a float. Since there is no automatic conversion possible from float to integer, changes to the parameter within the function or procedure can not be propagated back to the calling variable. A warning message is given when this occurs.

	Type 		Coercible to

character string
byte character string short integer long logical float double
short character string integer long logical float double
integer string long logical float double
long logical string float double
float logical string double
double logical string

A special set of functions exists for forcing the coercion in the reverse direction. For example, the function doubletointeger can be used to convert a double precision number into an integer. This operation will cause the decimal portion to be truncated, and information will be lost. See NCL functions and procedures for other similar functions.

Creating data

Data exist in NCL either as a single scalar value or a multi-dimensional array of scalar elements. The term value in NCL can refer to either a single scalar value or a multi-dimensional array of a specific data type.

There are three ways data can be created:

Constants and Arrays of constants

Constant values are values that are either entered at the command line or are written textually in an NCL script. There are only three data types in which constant values are expressed: float, integer, and string. Floating point constants are entered either in scientific notation or as numbers with a decimal point. It is not possible to specify a double precision constant. However it is possible to assign a floating point constant to a double precision variable. Integer constants are entered without decimal points. String constants' values contain characters enclosed in quotes (").

The following are examples of single scalar constant values:

Floating Point Constants:

	3.141592	1e-12	2.

Integer Constants:

	100	1

String Constants:

	"a"	"Hello World"
NOTE: There is currently no way to specify characters literally. The stringtochar function can be used to convert a string to an array of characters though.

Arrays of constants can be constructed using the array designator characters "(/" and "/)" with constant values separated by commas. Multi-dimensional constant arrays can be created by nesting the array designator characters. The following are examples of constant arrays. Each example uses the assignment statement to assign the constant arrays to a variable.

Creating new data arrays

All numeric data, string, character, logical, and graphic types can be created using the new statement. It is important to note that new is not a function; it is a statement. Because new is a statement, there are two ways to use it, and it is possible to use a type keyword as an argument to new. The two possible ways to use new are:

The new statement takes, as parameters, an array of integer dimension sizes, the keyword for the data type, and optionally a missing value to assign to each element of the new data array. The following creates a [5]x[6]x[7] three-dimensional float array filled with the default missing value for float types and the attribute _FillValue is also set:

The default missing values are:

	logical   : -1
        byte      :  0377 (octal)
	short     : -99
	integer   : -999
	long	  : -9999
	float     : -999
	double    : -9999
	graphic   : -9999
	file      : -9999
 	character : 0 or '\0' for those who know C
	string    : "missing"

The following is an example of how to assign a specific missing value. The result is an array filled with -1e12 at every index.

Importing data arrays and files

Data can be read in to NCL in a variety of ways. If data exist as a UNIX file in either ASCII, C, or Fortran binary data, the data can be read in to NCL with one of the following NCL intrinsic functions respectively, asciiread, cbinread, or fbinrecread. Each of these functions requires the user to enter a string file name, a dimension size array similar to the new command, and finally a string denoting what type the data are stored in. These functions return a single array of a single data type per call. Currently, support for binary or ASCII files containing more than one array is not officially supported. The NCL scientific tutorial contains some examples of how to read multiple records from a Fortran binary file.

Another way to import data is to import from a supported file format. Supported file formats are specially recognized data formats that store variables and other information. Supported formats allow direct access to variables and other information in data files through NCL. This access is very different than the abovementioned methods of reading files. NCL has a special syntax for referencing variables in files that simplifies the importation of external data. The addfile function is used to open external files that are in a supported format. The addfile function returns a reference to a file that is used to access data within that file. This is all covered in the variables section of this reference guide.

For specific information on a supported file format, see the Supported data format information section of the reference guide. Currently, with version 4.1, these formats are CCM history tape, netCDF, GRIB, and HDF.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.20 $ $Date: 1998/12/23 18:39:17 $