;+
;
; @file_comments
; Check that the input array has size and dimensions
; compatible with the domain that was defined with the previous call
; of <pro>domdef</pro>.
;
; @categories
; Compatibility
;
; @param sz {in}{required}
;
; @param nx {in}{required}
;
; @param ny {in}{required}
;
; @param nz {in}{required}
;
; @param jpi {in}{required}
;
; @param jpj {in}{required}
;
; @param jpk {in}{required}
;
; @param jpt {in}{required}
;
; @returns
; -1
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;  - 10 juin 2000.
;  - June 2005: S. Masson rewrite all.
;
; @version
; $Id$
;
; @hidden
;
;-
FUNCTION err_mess, sz, jpi, nx, jpj, ny, jpk, nz, jpt
;
  compile_opt idl2, strictarrsubs
;
  IF n_elements(sz EQ 1) THEN $
    RETURN, report(['Error: ' $
                  , 'the vector size (' + tostr(sz) + ') is incompatible' $
                  , 'with the domain dimensions ' $
                  , '[jpi/nx, jpj/ny, jpk/nz, jpt] = [' $
                  + strtrim(jpi, 1) + '/' + strtrim(nx, 1) $
                  + ', ' + strtrim(jpj, 1) + '/' + strtrim(ny, 1) $
                  + ', ' + strtrim(jpk, 1) + '/' + strtrim(nz, 1) $
                  + ', ' + strtrim(jpt, 1) + ']'], /simple)
  RETURN, report(['Error: ' $
                  , 'the array dimensions ' + tostr(sz) + ' are incompatible' $
                  , 'with the domain dimensions ' $
                  , '[jpi/nx, jpj/ny, jpk/nz, jpt] = [' $
                  + strtrim(jpi, 1) + '/' + strtrim(nx, 1) $
                  + ', ' + strtrim(jpj, 1) + '/' + strtrim(ny, 1) $
                  + ', ' + strtrim(jpk, 1) + '/' + strtrim(nz, 1) $
                  + ', ' + strtrim(jpt, 1) + ']'], /simple)
END
;
;+
;
; @categories
; Compatibility
;
; @param field {in}{required}{type=array or struct}
; an array or a structure that can be read by the function
; <pro>litchamp</pro>
;
; @param nx {in}{optional}{default=define by <pro>grille</pro>}
;
; @param ny {in}{optional}{default=define by <pro>grille</pro>}
;
; @param nz {in}{optional}{default=define by <pro>grille</pro>}
;
; @param firstx {in}{optional}{default=define by <pro>grille</pro>}
;
; @param firsty {in}{optional}{default=define by <pro>grille</pro>}
;
; @param firstz {in}{optional}{default=define by <pro>grille</pro>}
;
; @param lastx {in}{optional}{default=define by <pro>grille</pro>}
;
; @param lasty {in}{optional}{default=define by <pro>grille</pro>}
;
; @param lastz {in}{optional}{default=define by <pro>grille</pro>}
;
; @keyword WDEPTH
; To specify that we are at W level
;
; @returns
; an array with dimensions matching the domain or -1 if there is an error.
;
; @uses
; <pro>cm_4mesh</pro>
; <pro>cm_4cal</pro>
;
; @examples
;
;   IDL> help, fitintobox(findgen(jpi,jpj))
; <Expression>    FLOAT     = Array[41, 3]
;   IDL> help, fitintobox(findgen(jpi,jpj,78))
; Error:
; the array dimensions [180,148,78] are incompatible
; with the domain dimensions
; [jpi/nx, jpj/ny, jpk/nz, jpt] = [180/41, 148/3, 31/31, 1]
; <Expression>    INT       =       -1
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;          10 juin 2000.
;          June 2005: S. Masson rewrite all.
;
; @version
; $Id$
;
;-
FUNCTION fitintobox, field, nx, ny, nz, firstx, firsty $
                   , firstz, lastx, lasty, lastz, WDEPTH=wdepth
;
  compile_opt idl2, strictarrsubs
;
@cm_4mesh
@cm_4cal
  IF NOT keyword_set(key_forgetold) THEN BEGIN
@updatenew
  ENDIF
;---------------------
  arr = litchamp(field)
  IF n_params() EQ 1 THEN grille, -1, -1, -1, -1, nx, ny, nz $
    , firstx, firsty, firstz, lastx, lasty, lastz, WDEPTH = wdepth
;--------------------------------------------------------------
;--------------------------------------------------------------
; case according the number of dimensions of the array
;--------------------------------------------------------------
;--------------------------------------------------------------
  sz = size(arr)
  case sz[0] of
;--------------------------------------------------------------
    0:BEGIN                     ; scalar
;--------------------------------------------------------------
      return, report('Error: scalar value = ' + strtrim(arr, 1), /simple)
    END
;--------------------------------------------------------------
    1:BEGIN                     ; 1D arrays
;--------------------------------------------------------------
      CASE 1 OF
; x arrays
        sz[1] EQ jpi                                                   :arr = (temporary(arr))[firstx:lastx                               ]
        sz[1] EQ  nx                                                   :
; y arrays
        sz[1] EQ jpj                                                   :arr = (temporary(arr))[              firsty:lasty                 ]
        sz[1] EQ  ny                                                   :
; z arrays
        sz[1] EQ jpk                                                   :arr = (temporary(arr))[                            firstz:lastz   ]
        sz[1] EQ  nz                                                   :
; t arrays
        sz[1] EQ jpt                                                   :
        ELSE:return, err_mess(sz[1], jpi, nx, jpj, ny, jpk, nz, jpt)
      ENDCASE
    END
;--------------------------------------------------------------
    2:BEGIN                     ; 2D arrays
;--------------------------------------------------------------
      CASE 1 OF
; xy arrays
        sz[1] EQ jpi AND sz[2] EQ jpj                                  :arr = (temporary(arr))[firstx:lastx, firsty:lasty                 ]
        sz[1] EQ jpi AND sz[2] EQ  ny                                  :arr = (temporary(arr))[firstx:lastx,            *                 ]
        sz[1] EQ  nx AND sz[2] EQ jpj                                  :arr = (temporary(arr))[           *, firsty:lasty                 ]
        sz[1] EQ  nx AND sz[2] EQ  ny                                  :arr = (temporary(arr))[           *,            *                 ]
; x(y)z arrays
        sz[1] EQ jpi AND ny EQ 1      AND sz[2] EQ jpk                 :arr = (temporary(arr))[firstx:lastx, firstz:lastz   ]
        sz[1] EQ jpi AND ny EQ 1      AND sz[2] EQ  nz                 :arr = (temporary(arr))[firstx:lastx,            *   ]
        sz[1] EQ  nx AND ny EQ 1      AND sz[2] EQ jpk                 :arr = (temporary(arr))[           *, firstz:lastz   ]
        sz[1] EQ  nx AND ny EQ 1      AND sz[2] EQ  nz                 :
; (x)yz arrays
        nx EQ 1      AND sz[1] EQ jpj AND sz[2] EQ jpk                 :arr = (temporary(arr))[              firsty:lasty, firstz:lastz   ]
        nx EQ 1      AND sz[1] EQ jpj AND sz[2] EQ  nz                 :arr = (temporary(arr))[              firsty:lasty,            *   ]
        nx EQ 1      AND sz[1] EQ  ny AND sz[2] EQ jpk                 :arr = (temporary(arr))[                         *, firstz:lastz   ]
        nx EQ 1      AND sz[1] EQ  ny AND sz[2] EQ  nz                 :
; xt arrays
        sz[1] EQ jpi                                   AND sz[2] EQ jpt:arr = (temporary(arr))[firstx:lastx                            , *]
        sz[1] EQ  nx                                   AND sz[2] EQ jpt:
; yt arrays
                         sz[1] EQ jpj                  AND sz[2] EQ jpt:arr = (temporary(arr))[              firsty:lasty              , *]
                         sz[1] EQ  ny                  AND sz[2] EQ jpt:
; zt arrays
                                          sz[1] EQ jpk AND sz[2] EQ jpt:arr = (temporary(arr))[                            firstz:lastz, *]
                                          sz[1] EQ  nz AND sz[2] EQ jpt:
        ELSE:return, err_mess(sz[1:2], jpi, nx, jpj, ny, jpk, nz, jpt)
      ENDCASE
    END
;--------------------------------------------------------------
    3:BEGIN                     ; 3D arrays
;--------------------------------------------------------------
      CASE 1 OF
; xyz arrays
        sz[1] EQ jpi AND sz[2] EQ jpj AND sz[3] EQ jpk                 :arr = (temporary(arr))[firstx:lastx, firsty:lasty, firstz:lastz   ]
        sz[1] EQ jpi AND sz[2] EQ  ny AND sz[3] EQ jpk                 :arr = (temporary(arr))[firstx:lastx,            *, firstz:lastz   ]
        sz[1] EQ  nx AND sz[2] EQ jpj AND sz[3] EQ jpk                 :arr = (temporary(arr))[           *, firsty:lasty, firstz:lastz   ]
        sz[1] EQ  nx AND sz[2] EQ  ny AND sz[3] EQ jpk                 :arr = (temporary(arr))[           *,            *, firstz:lastz   ]
        sz[1] EQ jpi AND sz[2] EQ jpj AND sz[3] EQ  nz                 :arr = (temporary(arr))[firstx:lastx, firsty:lasty,            *   ]
        sz[1] EQ jpi AND sz[2] EQ  ny AND sz[3] EQ  nz                 :arr = (temporary(arr))[firstx:lastx,            *,            *   ]
        sz[1] EQ  nx AND sz[2] EQ jpj AND sz[3] EQ  nz                 :arr = (temporary(arr))[           *, firsty:lasty,            *   ]
        sz[1] EQ  nx AND sz[2] EQ  ny AND sz[3] EQ  nz                 :
; xyt arrays
        sz[1] EQ jpi AND sz[2] EQ jpj                  AND sz[3] EQ jpt:arr = (temporary(arr))[firstx:lastx, firsty:lasty,               *]
        sz[1] EQ jpi AND sz[2] EQ  ny                  AND sz[3] EQ jpt:arr = (temporary(arr))[firstx:lastx,            *,               *]
        sz[1] EQ  nx AND sz[2] EQ jpj                  AND sz[3] EQ jpt:arr = (temporary(arr))[           *, firsty:lasty,               *]
        sz[1] EQ  nx AND sz[2] EQ  ny                  AND sz[3] EQ jpt:
; (x)yzt arrays
        nx EQ 1      AND sz[1] EQ jpj AND sz[2] EQ jpk AND sz[3] EQ jpt:arr = (temporary(arr))[              firsty:lasty, firstz:lastz, *]
        nx EQ 1      AND sz[1] EQ jpj AND sz[2] EQ  nz AND sz[3] EQ jpt:arr = (temporary(arr))[              firsty:lasty,            *, *]
        nx EQ 1      AND sz[1] EQ  ny AND sz[2] EQ jpk AND sz[3] EQ jpt:arr = (temporary(arr))[                         *, firstz:lastz, *]
        nx EQ 1      AND sz[1] EQ  ny AND sz[2] EQ  nz AND sz[3] EQ jpt:
; x(y)zt arrays
        sz[1] EQ jpi AND ny EQ 1      AND sz[2] EQ jpk AND sz[3] EQ jpt:arr = (temporary(arr))[firstx:lastx,               firstz:lastz, *]
        sz[1] EQ jpi AND ny EQ 1      AND sz[2] EQ  nz AND sz[3] EQ jpt:arr = (temporary(arr))[firstx:lastx,                          *, *]
        sz[1] EQ  nx AND ny EQ 1      AND sz[2] EQ jpk AND sz[3] EQ jpt:arr = (temporary(arr))[           *,               firstz:lastz, *]
        sz[1] EQ  nx AND ny EQ 1      AND sz[2] EQ  nz AND sz[3] EQ jpt:
        ELSE:return, err_mess(sz[1:3], jpi, nx, jpj, ny, jpk, nz, jpt)
      ENDCASE
    END
;--------------------------------------------------------------
    4:BEGIN                     ; 4D arrays
;--------------------------------------------------------------
      CASE 1 OF
; xyzt arrays
        sz[1] EQ jpi AND sz[2] EQ jpj AND sz[3] EQ jpk AND sz[4] EQ jpt:arr = (temporary(arr))[firstx:lastx, firsty:lasty, firstz:lastz, *]
        sz[1] EQ jpi AND sz[2] EQ  ny AND sz[3] EQ jpk AND sz[4] EQ jpt:arr = (temporary(arr))[firstx:lastx,            *, firstz:lastz, *]
        sz[1] EQ  nx AND sz[2] EQ jpj AND sz[3] EQ jpk AND sz[4] EQ jpt:arr = (temporary(arr))[           *, firsty:lasty, firstz:lastz, *]
        sz[1] EQ  nx AND sz[2] EQ  ny AND sz[3] EQ jpk AND sz[4] EQ jpt:arr = (temporary(arr))[           *,            *, firstz:lastz, *]
        sz[1] EQ jpi AND sz[2] EQ jpj AND sz[3] EQ  nz AND sz[4] EQ jpt:arr = (temporary(arr))[firstx:lastx, firsty:lasty,            *, *]
        sz[1] EQ jpi AND sz[2] EQ  ny AND sz[3] EQ  nz AND sz[4] EQ jpt:arr = (temporary(arr))[firstx:lastx,            *,            *, *]
        sz[1] EQ  nx AND sz[2] EQ jpj AND sz[3] EQ  nz AND sz[4] EQ jpt:arr = (temporary(arr))[           *, firsty:lasty,            *, *]
        sz[1] EQ  nx AND sz[2] EQ  ny AND sz[3] EQ  nz AND sz[4] EQ jpt:
        ELSE:return, err_mess(sz[1:4], jpi, nx, jpj, ny, jpk, nz, jpt)
      ENDCASE
    END
    ELSE:return, report('Error: fitintobox is managing arrays with a maximum of 4 dimensions', /simple)
  ENDCASE

  return, arr
end