NCL Home > Documentation > Functions > Array manipulators, Array creators

dim_pad_extend

Extend (i.e., expand, append, pad) an existing array along the 'record dimension' to a user specified size.

Available in version 6.5.0 and later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"      ; These four libraries are automatically
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"       ; loaded from NCL V6.4.0 onward.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"   ; No need for user to explicitly load.
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

	function dim_pad_extend (
		x        ,           
		nExt [1] : integer,  
		dims [1] : integer,  
		opt  [1] : logical   
	)

	return_val  :  typeof(x))

Arguments

x

An array of any dimensionality and type.

nExt

Extend (aka: append, extend, pad) the 'size' of the user specified dimension (dims) by this length.

dims

The dimension number of x to pad. Currently, only dims=0 or 1 is supported.

opt

Currently not used. Set to False.

Description

Extending the specified dimension (dims) of an array may be necessary when the array dimension size of a variable is different than the requirements of an application (eg: array operation or function requirement).

Meta data are preserved except for the coordinate variable along the dimension specified by dims. If there is no existing dimension name, a new dimension name (extend_nExt). See Example 1.

FYI: The reason for using additional descriptive words for 'extend' such as "expand", "append", "pad", etc is that other languages use different terms.

See Also

Array manipulators

Examples

Example 1:

Extend (expand, append, pad) an existing array ('y') of size 'ny' (here, 9) by a user specified number (nExt). This example uses NCL's reassignment operator [ := ] is used to allow the original array to be over-written (reassigned). Since, 'y' is a one-dimensional array, dims=0. Also, since there is no dimension name, a dimension name extend_nExt=extend_24 is created. 


  y    = ispan(13,21,1)      ; y(ny); y(9)
  y   := dim_pad_extend(y,81,0,False)  ; Next=81;  y(ny+nExt); y(9+81); y(90) 
  print(y)
The output is: 

  Variable: y
  Type: integer
  Total Size: 48 bytes
              24 values
  Number of Dimensions: 1
  Dimensions and sizes:   [extend_81 | 90]       ; <=== created dimension name
  Coordinates: 
  Number Of Attributes: 1
    _FillValue :  -2147483647
    Next :        81

  (0)     13
  (1)     14
  (2)     15
  (3)     16
  (4)     17
  (5)     18
  (6)     19
  (7)     20
  (8)     21
  (9)     -2147483647
  (10)    -2147483647
  (11)    -2147483647
  [SNIP]
  (88)   -2147483647
  (89)   -2147483647
  (378)   -2147483647
Note: Instead of reassignment, a new array could have been created: 

  Y = dim_pad_extend(y,nExt,0,False)  ; Y(379)