# dim_gbits

Unpacks bit chunks from the rightmost dimension of the input array.

## Prototype

function dim_gbits ( npack : numeric, ; byte, ubyte, short, ushort, integer ibit : integer, nbits : integer, nskip : integer, iter : integer ) return_val :typeof(npack)

## Arguments

*npack*

The array to be unpacked. It can be a byte, ubyte, short, ushort, or integer array of any dimensionality. The rightmost dimension will be unpacked. (The recognition of ubyte and ushort types was added in NCL V6.0.0)

*ibit*

A bit-count offset to be used before the first bit chunk is unpacked.
For example, if *npack* is one-dimensional and if
*ibit*=3 and *nbits*=5, then 3 bits in *npack*
will be skipped and the next 5 bits will be unpacked into the returned
array.

*nbits*

The number of bits in each bit chunk to be unpacked.

*nskip*

The number of bits to skip between each bit chunk to be unpacked (after the first bit chunk has been unpacked).

*iter*

The number of bit chunks to be unpacked. Usually, *iter* is
the same size as the rightmost dimension of *npack*.

## Return value

The return array will be the same type as *npack*. The dimensionality
will depend on the remaining input parameters (see description and
examples below).

## Description

**Important note**: As of
version 6.0.0, bytes are now
signed (instead of unsigned). Use the "ubyte" type if you need to
mimic the behavior of the old unsigned byte type.

**dim_gbits** unpacks bit chunks from the input array
*npack* into an output array *isam*. *iter* bit
chunks of length *nbits* with *nskip* bits being skipped
between each bit chunk in the input array are unpacked into
*isam*. Each bit chunk in the input array is unpacked into a
separate word in *isam*, right-justified with zero-fill.
Initially, *ibit* bits will be skipped at the beginning of the
input array before unpacking.

The following depicts the role of each argument. Assume
*ibit*=5, *nbits*=2, *nskip*=3 and
*iter*=4:

npack: 0101011111100100110100 ^^^^^ skip first 5 bits ^^ iter=1 extract 11 ==> integer 3 ^^^ skip 3 bits ^^ iter=2 extract 10 ==> integer 2 ^^^ skip 3 bits ^^ iter=3 01 ==> integer 1 ^^^ skip 3 bits ^^ iter=4 00 ==> integer 0

## See Also

## Examples

**Example 1**

Assume *x* is a one dimensional array of length *N*.

xchunk =3 bits will be skipped at the beginning ofdim_gbits(x,3,6,9,2)

*x*. The next 6 bits will be unpacked into

*xchunk*(0) right-justified with zero-fill. 9 bits will be skipped in

*x*. The next six bits of

*x*will be unpacked into

*xchunk*(1) right-justified with zero-fill. The return array

*xchunk*will be the same type as

*x*and be of length 2.

**Example 2**

Assume *x* is a 5D array with dimensions *ntim* x
*klvl* x *nlat* x *mlon* x *N* and of
type byte. Then:

xchunk =dim_gbits(x,0,2,6,N)

0 bits will be skipped at the beginning of the rightmost dimension of
*x*. The first 2 bits of the rightmost dimension will be
unpacked into the rightmost dimension of *xchunk*({...},0)
right-justified with zero-fill. 6 bits will be skipped in the
rightmost dimension of *x*. The next 2 bits of *x* will
be unpacked into *xchunk*({...},1) right-justified with
zero-fill. This will continue *N* times. The return array
*xchunk* will be the same type and shape as *x*.