Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  Markwardt  >  INPUTFORM

INPUTFORM

INPUTFORM

Name


  INPUTFORM

Author


  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  craigm@lheamail.gsfc.nasa.gov

Purpose


  Generates expression string from an IDL value

Calling Sequence


  STRING = INPUTFORM(VALUE, ERRMSG=ERRMSG, STATUS=STATUS, ...)

Description



  The INPUTFORM function converts an IDL data value into its string
  representation, suitable for execution at the IDL command line or
  with EXECUTE(). This is similar to the "InForm" output
  representation of Mathematica, which formats output so that it can
  be entered again on the command line. INPUTFORM() is a
  specialized form of STRING().
  For example, the value DBLARR(2,2) has the default representation
      '[[0D,0],[0D,0]]'
  The formal goal of INPUTFORM is for the resulting textual
  expression to be an exact representation of the original data.
  Several other output options can be selected by using the /ZERO or
  /ARRAY_NOTATION keywords.
  Therefore, given the original value VARIABLE, then after executing
      R = EXECUTE( 'variable1 = '+INPUTFORM(variable) )
  The value, type, and dimension of VARIABLE1 and VARIABLE will be
  the same.
  Such behavior might useful in several circumstances:
      * for printing values meant to be "pasted" back into the
        command line by the user;
      * for constructing command arguments to be EXECUTE()'d;
      * for saving values in ASCII format for later execution.
  OUTPUT OPTIONS:
  The output of INPUTFORM can be controlled in the following ways.
  See the EXAMPLES section for examples of each kind of behavior.
      * By default, the output will replicate the exact values of the

Input


      * If the /ZERO keyword parameter is set, then the output will
        match the type and structure of the input, but all values
        will be zero or blank, including IDL strings and structures.
        This is useful if one wants to make a "blank template" from
        an existing IDL data structure.
      * If the /ARRAY_NOTATION keyword parameter is set, then any
        input arrays are converted to INTARR(), DBLARR(), STRARR().
        Scalars appear as in the input. Obviously the contents of
        arrays will be zero/blank in this case. The combination of
        /ZERO and /ARRAY_NOTATION produces a nice short-hand
        blank template.
  LIMITATIONS:
 
  It should be noted that the IDL parser is not perfect.
  While IDL has many data types, not all expressions are
  representable as a textual string. Pointers and objects can be
  represented. Examples of the parser limitation include,
      * array expressions can have no more than 90 elements;
      * bracketed array notation cannot be nested too deeply;
      * anonymous structure arrays have no textual representation;
  Given these limitations, the user of this routine must be prepared
  for failure and have contingency plans. Error messages and status
  indicators are provided to facilitate this. INPUTFORM() does not
  call MESSAGE, so it should never intentionally crash.
  Also, consider that the textual representation can never really be
  suitable for very large arrays. The internal algorithm is thus
  not optimized for speed as heavily numeric routines might be, and
  instead tries to make the output slightly more readable.

Inputs



  VALUE - the IDL value to be converted. Any value which has a
          legal textual representation is permitted.

Keywords



  ARRAY_NOTATION - if set, then any arrays in the input will be
            replaced by their xxxARR() equivalent.
  STATUS - upon return, a status indicator. A value of zero
            indicates failure; one indicates success.
  ERRMSG - upon return, a string message indicating the reason for a
            failure, if any. The empty string ('') indicates
            success.
  MAX_DIMENSIONS - maximum number of array dimensions permitted in
                    VALUE. The conversion fails if the maximum is
                    exceeded.
                    Default: any number of dimensions is permitted.
                    NOTE: IDL does not permit deep nesting, for
                    dimensions greater than three.
  MAX_ELEMENTS - maximum number of elements permitted in VALUE. The
                  conversion fails if the maximum is exceeded.
                  Default: any number of elements is permitted.
                  NOTE: the conversion may still fail if any array
                  dimension exceeds 90.
  MAX_LEN - approximate maximum length of returned string. If large
            string expressions exceed this size as they are being
            composed internally, they will be terminated by a '...'
            ellipsis and returned. This value is to be used as a
            guideline by INPUTFORM(); the precise limit may not be
            adhered to.
            Default: 16384L
  MAX_TAGS - maximum number of structure tags permitted in VALUE.
              The conversion fails if the maximum is exceeded.
              Default: any number of tags is permitted.
  N_FLOAT - for floating point numerical values, N_FLOAT gives the
            number of decimal digits to print. By definition,
            setting this keyword will involve the loss of some
            precision compared to the original value.
            Default: full precision is printed.
  ZERO - if set, then the output command will have zero values for
          all fields, regardless of the contents of the input data.
           

Returns


  The resulting converted string, if successful. Upon failure,
  STATUS is set to zero and the empty string ('') is returned.

Example


 
  Convert a double array to text using the default output option,
    IDL> x = [[1,2],[3,4]]
    IDL> print, inputform(x)
    ---> [[1,2],[3,4]]
  The same input, but using the /ZERO and /ARRAY_NOTATION options,
    IDL> print, inputform(x, /zero)
    ---> [[0,0],[0,0]]
    IDL> print, inputform(x, /array_notation)
    ---> INTARR(2L,2L)
  Convert a structure,
    IDL> y = create_struct('s1',5,'s2','strvalue','s3',[1,2,3])
    IDL> print, inputform(y)
    ---> [{S1:5,S2:'strvalue',S3:[1,2,3]}]
  Also with /ZERO and /ARRAY_NOTATION options,
    IDL> print, inputform(y, /zero)
    ---> {S1:0,S2:'',S3:[0,0,0]}
    IDL> print, inputform(y, /array_notation)
    ---> {S1:5,S2:'strvalue',S3:INTARR(3L)}
    (Note that in the final case with /ARRAY_NOTATION alone, S3 is
      replaced by INTARR(), but that the scalars are left unchanged.)
    IDL> print, inputform(y, /zero, /array_notation)
    ---> {S1:0,S2:'',S3:INTARR(3L)}
    (With /ZERO and /ARRAY_NOTATION combined, then all fields are
      zero or blank).

See Also



  STRING, PRINT, HELP, HELPFORM

Modification History


  Written, CM, 10 Apr 2000
  Added HELPFORM to SEE ALSO, CM, 04 Jul 2000
  Corrected case of scalar float value, CM, 13 Jul 2000
  Put a space after float types like 1E or 1D to ease parsing, CM,
    18 Jul 2000
  Add ability to print INPUTFORM of pointers, CM, 09 Dec 2002
  Add ability to print INPUTFORM of object pointers, CM, 01 Oct 2003
  Bug fix: actually obey MAX_ELEMENTS (was being ignored), CM, 22
    Oct 2006
  Change to square-bracket array syntax, CM, 27 Feb 2007
  Add the ZERO and ARRAY_NOTATION keywords; handle NAN and INFINITY
    values properly, CM, 02 Jun 2009
  Add N_FLOAT keyword, CM, 13 Nov 2010
 
  $Id: inputform.pro,v 1.8 2010/11/13 09:27:36 cmarkwar Exp $



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us