new

Creates an NCL variable.

Prototype

	function new (
		dimension_sizes [*] : integer,  
		vartype             : string,   
		parameter                       
	)

	return_val [dimension_sizes] :  vartype

Arguments

The dimension sizes of the NCL variable to create.

The type of the NCL variable to create. This can either be a string, like "float", or just the word float (without quotes).

(optional)
The value for parameter can either be a missing value (which becomes the _FillValue attribute), or the string "No_FillValue" to indicate that no _FillValue attribute is to be created. (The "No_FillValue" option was added in version a034.) This is an optional argument, so if it is not set, then a default missing value for the variable's type will be used.

Description

new is not an NCL function, but rather an NCL statement. It is being included in the function documentation because it behaves very much like an NCL function.

The new statement is used to create a new NCL variable, by giving it dimension sizes, the type, and optionally a value for the missing value, or no missing value at all. If parameter is not set, then a default missing value appropriate for the variable's type will be assigned. The variable created will be filled with this missing value.

If "No_FillValue" (added in version a034) is used for the parameter argument, then no _FillValue attribute is assigned to the variable, and the values will be undefined. This option should only be used if you will be initializing the whole array at some point. If a variable was previously defined before, and you try to recreate it using new with the "No_FillValue" parameter, then the _FillValue attribute and its value will be unchanged and the elements of the array now have all undefined values.

Using new is not the only way to create an NCL variable. You can also do this with a simple assignment statement:

  x = 5.0                                       ; float scalar  
  i = (/ (/1,2,3/), (/4,5,6/), (/7,8,9/) /)     ; 3 x 3 integer array
  d = 100000.d                                  ; double scalar
  c = stringtochar("abcde")                     ; character array

Some NCL types cannot be created using an assignment statement (like character and byte), so you either need to use new, one of the many type converter functions, or else read it off a file.

See Also

delete, destroy, NCL "new" statement

Examples

Example 1

This example shows how to create some arrays of various types and print information about them:

  i = new((/2,3/),"integer")
  x = new(5,float)
  b = new(1,byte)
  printVarSummary(i)    
  printVarSummary(x)
  printVarSummary(b)

Both i and x will have default missing values of -999, which is the default missing value for both integers and floats. The default missing value for b is 377 octal (255 decimal).

Example 2

This example shows how to create a double variable and assign a missing value of 0.0:

  y = new(5,double,0)
  printVarSummary(y)

Example 3

Assume x is some multi-dimensional variable of unknown type and a missing value. Assume further that you want to make a copy of this variable, but you don't want to assign any values to it just yet:

  xnew = new(dimsizes(x),typeof(x),x@_FillValue)

Example 4

This example shows how to create a float array with no _FillValue attribute set:

  x = new((/64,128/),float,"No_FillValue")

The values in x will be undefined.