NCL Home > Documentation > Manuals > Reference

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. File type values are returned by the addfile intrinsic function, while the addfiles function returns a list type value.

	string		N/A
	character	8bits
	graphic		N/A
	file		N/A
	list            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:

By entering constant values.
By using the new command to allocate space for a multi-dimensional value.
By using functions like asciiread, cbinread, fbinrecread, and addfile.

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 four data types in which constant values are expressed: float, double, integer, and string. Floating point constants are entered either in scientific notation or as numbers with a decimal point. Double precision constants are entered by replacing the 'e' or 'E' in normal scientific notation with 'd' or 'D', or simply by adding 'd' or 'D' as a suffix to any number. 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.

Double Precision Constants:

	3.14159265358979d0   1d-12   2D

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.

1D Floating Point Constant Array:

	var0 = (/ 1.2, 2.3, 3.4, 4.5, 5.6, 6.7 /)

[2]x[6] 2D Floating Point Constant Array:

	var1 = (/ (/ 1.2, 2.3, 3.4, 4.5, 5.6, 6.7 /), (/ 7.8, 8.9, 9.1, 10.2, 11.3, 12.4/) /)

1D Double Precision Constant Array:

	var0 = (/ 1.2d, 2.3d, 3.4d, 4.5d, 5.6d, 6.7d /)

1D Integer Constant Array:

	var2 = (/ -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5 /)

1D String Constant Array:

	var3 = (/ "one", "two", "three", "four", "five" /)

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, it is possible to use a type keyword as an argument to new. There are three possible ways to use new:

Create an array of data with a specific missing value assigned to each element.
Create the array of data using the default missing value.
Create the array of data with no missing value.

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, or the "No_FillValue" string to indicate no missing values are to be assigned. (Recognition of "No_FillValue" was added in version a034.)

Here are three examples showing each of the different ways to use new:

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:

        a = new( (/ 5, 6, 7 /), float)
	print(a)


	Variable: a
	Type: float
	Total Size: 840 bytes
            	210 values
	Number of Dimensions: 3
	Dimensions and sizes:   [5] x [6] x [7]
	Coordinates: 
	Number Of Attributes: 1
  		_FillValue :  -999
	(0,0,0) -999
	(0,0,1) -999
	(0,0,2) -999
	 . . .

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.
The following is an example of how to create an array of data with no missing values. Note that the data array will not be initialized to any particular value, so you must only use this option if you know you will be initializing the whole array at some point.
If variable a was previously defined before the above statement was called and it had a _FillValue attribute, then the attribute and its value will be unchanged even though the elements of the array now have all undefined values.

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 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.

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.