;+ ; NAME: ; CMREPLICATE ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Replicates an array or scalar into a larger array, as REPLICATE does. ; ; CALLING SEQUENCE: ; ARRAY = CMREPLICATE(VALUE, DIMS) ; ; DESCRIPTION: ; ; The CMREPLICATE function constructs an array, which is filled with ; the specified VALUE template. CMREPLICATE is very similar to the ; built-in IDL function REPLICATE. However there are two ; differences: ; ; * the VALUE can be either scalar or an ARRAY. ; ; * the dimensions are specified as a single vector rather than ; individual function arguments. ; ; For example, if VALUE is a 2x2 array, and DIMS is [3,4], then the ; resulting array will be 2x2x3x4. ; ; INPUTS: ; ; VALUE - a scalar or array template of any type, to be replicated. ; NOTE: These two calls do not produce the same result: ; ARRAY = CMREPLICATE( 1, DIMS) ; ARRAY = CMREPLICATE([1], DIMS) ; In the first case the output dimensions will be DIMS and ; in the second case the output dimensions will be 1xDIMS ; (except for structures). That is, a vector of length 1 is ; considered to be different from a scalar. ; ; DIMS - Dimensions of output array (which are combined with the ; dimensions of the input VALUE template). If DIMS is not ; specified then VALUE is returned unchanged. ; ; RETURNS: ; The resulting replicated array. ; ; EXAMPLE: ; x = [0,1,2] ; help, cmreplicate(x, [2,2]) ; INT = Array[3, 2, 2] ; Explanation: The 3-vector x is replicated 2x2 times. ; ; x = 5L ; help, cmreplicate(x, [2,2]) ; LONG = Array[2, 2] ; Explanation: The scalar x is replicated 2x2 times. ; ; SEE ALSO: ; ; REPLICATE ; ; MODIFICATION HISTORY: ; Written, CM, 11 Feb 2000 ; Fixed case when ARRAY is array of structs, CM, 23 Feb 2000 ; Apparently IDL 5.3 can't return from execute(). Fixed, CM, 24 Feb ; 2000 ; Corrected small typos in documentation, CM, 22 Jun 2000 ; Removed EXECUTE() call by using feature of REBIN() new in IDL 5.6, ; (thanks to Dick Jackson) CM, 24 Apr 2009 ; Remove some legacy code no longer needed after above change ; (RETVAL variable no longer defined; thanks to A. van Engelen), ; CM, 08 Jul 2009 ; Change to square bracket array index notation; there were reports ; of funny business with parenthesis indexing (thanks Jenny Lovell), ; CM, 2012-08-16 ; ;- ; Copyright (C) 2000, 2009, 2012, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-