STRINGS routines in *

All GAMAP Routines

List routines by category:
Atmospheric Sciences | Benchmarking | Color | Date/Time | Doc | File & I/O | BPCH Format | Scientific Data Formats | GAMAP Examples | GAMAP Internals | GAMAP Utilities | GAMAP Data Manipulation | GAMAP Models & Grids | GAMAP Plotting | General | Graphics | Math & Units | Plotting | Regridding | Strings | Structures | Time Series

List routines by alphabetical order:
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Last modified: Tue Apr 4 10:50:23 2017.


List of Routines


Routine Descriptions

FORMSTRLEN (FUNCTION)

[Next Routine] [List of Routines]
 NAME:
        FORMSTRLEN (function)

 PURPOSE:
        Return the (approximated) length of a string that 
        contains Hershey formatting characters. If the string 
        does not contain any formatting characters, the result
        equals that of STRLEN, otherwise it will be shorter.
        Hershey characters ('!'+1 char) are ignored, characters in
        super or subscript mode are counted as of width 0.6

 CATEGORY:
        Strings, Plotting

 CALLING SEQUENCE:
        LEN = FORMSTRLEN( S )

 INPUTS:
        S -> A string that may contain Hershey formatting characters.
             As with STRLEN, S may be a string array.

 KEYWORD PARAMETERS:
        none

 OUTPUTS:
        A float(!) value that gives the "true" length of the string

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PRINT, FORMSTRLEN('C2H6')
           4

        PRINT, FORMSTRLEN('C!L2!NH!L6!N')
           3.2

 MODIFICATION HISTORY:
        mgs, 27 Oct 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments 

(See /n/home09/ryantosca/IDL/gamap2/strings/formstrlen.pro)


GET_CHARSIZE_NORM

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_CHARSIZE_NORM

 PURPOSE:
        Returns the size in normal coordinates of an average
        character. The function accounts for !P.MULTI, !P.CHARSIZE,
        and the charsize scaling you pass to a plotting routine with
        the CHARSIZE keyword.

 CATEGORY:
        Plotting, Strings

 CALLING SEQUENCE:
        RESULT = GET_CHARSIZE_NORM( CHARSIZE [, Keywords ] )

 INPUTS:
        CHARSIZE -> A N-elements vector that gives the character
             size, in character unit: 1.0 is normal size, 2.0 is
             double size, etc. Default is 1.0. 
 
 KEYWORD PARAMETERS:
        /DEVICE -> Set this switch to compute the average character
             size in device units (which is usually pixel) instead of 
             the default normal coordinates.

 OUTPUTS:
        A N-by-2 array that gives average character size in
        normal coordinates:
            RESULT[*,0] are along the X direction, 
            RESULT[*,1] are along the Y direction. 

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLES:
        PRINT, GET_CHARSIZE_NORM

            0.00878049    0.0168750    


        PRINT, GET_CHARSIZE_NORM( /DEVICE )

             7.20000      10.8000


        MULTIPANEL, 6
        PRINT, GET_CHARSIZE_NORM( [1, 2, 3.5 ], /DEVICE )

           3.60000      7.20000      12.6000   ; => X sizes in pixel
           5.40000      10.8000      18.9000   ; => Y sizes in pixel          


 MODIFICATION HISTORY:
        phs,  3 Dec 2007: VERSION 1.00

(See /n/home09/ryantosca/IDL/gamap2/plotting/get_charsize_norm.pro)


GET_DEFAULTFORMAT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        GET_DEFAULTFORMAT (function)

 PURPOSE:
        Return format string that will produce legible and
        concise strings for a given value range. The format
        should be applied in a string() statement and the 
        string should be trimmed.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        MYFORMAT = GET_DEFAULTFORMAT(minval,maxval [,/LOG])

 INPUTS:
        MINVAL, MAXVAL -> the range of values that shall be 
            displayed with this format.

 KEYWORD PARAMETERS:
        /LOG -> set this keyword if you plan logarithmic labels.
            (changes behaviour for 0.001)

        DEFAULTLEN -> 1 or 2 strings with the default length 
            specification for 'f' and 'e' formats. If only one
            string is passed, it will be used for both, otherwise
            the first string applies to 'f' and the second to 'e'.
            Example: DEFAULTLEN='10.3' results in 'f10.3'.

        THRESHOLD -> threshold value to switch from 'f' to 'e' format.
            Default is '2' for linear and '3' for log scale. This
            value is determined by the negative decadal log of (maxv-minv)
            plus 2.

 OUTPUTS:
        MYFORMAT -> A format string (e.g. '(f14.2)' )

 SUBROUTINES:
        none

 REQUIREMENTS:
        none

 NOTES:
        None

 EXAMPLE:
        PRINT, GET_DEFAULTFORMAT( 0.01, 1. )
          '(f14.2)'

        PRINT, GET_DEFAULTFORMAT( 0.0001, 0.01 )
          '(e12.3)'

 MODIFICATION HISTORY:
        mgs, 17 Mar 1999: VERSION 1.00
        mgs, 25 Mar 1999: - added DEFAULTLEN keyword
        mgs, 19 May 1999: - DEFAULTLEN now converted to string.
                          - added THRESHOLD keyword
        bmy, 27 Sep 2002: TOOLS VERSION 1.51
                          - made default exponential format e12.2
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/get_defaultformat.pro)


ISALGEBRAIC (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALGEBRAIC (function)

 PURPOSE:
        Locates the position of algebraic characters in a string
        (e.g. locations that are EITHER digits '.' OR +/- signs).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        Result = ISALGEBRAIC( S [, Keywords ] )

 INPUTS:
        S -> The string to be tested.  

 KEYWORD PARAMETERS:

 OUTPUTS:
        Result -> The value of the function.  RESULT is an index array
            (integer) that contains as many elements as S has 
            characters.  If S is a single character, then RESULT will 
            be scalar. Where RESULT = 1, the corresponding characters 
            in S are algebraic.

 SUBROUTINES:

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        print, ISALGEBRAIC( '-100;+100' )
            ; prints 1 1 1 1 0 1 1 1 1 

 MODIFICATION HISTORY:
        bmy, 17 Nov 1998: VERSION 1.00
        mgs, 17 Nov 1998: - removed INVERT keyword. It's 
                            simply 1-isalgebraic
                          - added test for '.'
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalgebraic.pro)


ISALNUM (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALNUM (function)

 PURPOSE:
        IDL analog to the 'isalnum' routine in C.  Locates 
        alphanumeric characters ( A...Z, a...z, 0..9 ) in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        Result = ISALNUM( S )

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        Result -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are alphanumeric

 SUBROUTINES:
        ISALPHA (function)
        ISDIGIT (function)

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLE:
        print, isalnum( 'ABCD0123#' )
            ; prints, 1 1 1 1 1 1 1 1 0

        print, isalnum( '#' )
            ; prints 0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now uses ISALPHA and ISDIGIT
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalnum.pro)


ISALPHA (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISALPHA (function)

 PURPOSE:
        IDL analog to the 'isalpha' routine in C.  Locates the
        positions of alphabetic characters ( A...Z, a...z ).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISALPHA( S )

 INPUTS:
        S  -> The string to be tested. 

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are alphabetic.
        
 SUBROUTINES:
        ISUPPER (function)
        ISLOWER (function)

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        PRINT, ISALPHA( 'ABcd0123' )
          1 1 1 1 0 0 0 0

        PRINT, ISALPHA( '#' )
          0

 MODIFICATION HISTORY:
        bmy, 29 May 1998: VERSION 1.00
        bmy, 01 Jun 1998: - now returns 0 for condition FALSE
                          - fixed bug that allowed byte values from
                            91-96 to be treated as letters
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now uses ISUPPER and ISLOWER 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isalpha.pro)


ISDIGIT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISDIGIT (function)

 PURPOSE:
        IDL analog to the 'isdigit' routine in C.  Locates
        numeric characters ( '0' ... '9') in a string. 

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISDIGIT( S )

 INPUTS:
        S -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are numeric.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        print, isdigit( '3001ABcd' )
            ; prints, 1 1 1 1 0 0 0 0

        print, isdigit( '#' )
            ; prints 0

 MODIFICATION HISTORY:
        bmy, 29 May 1998: VERSION 1.00
        bmy, 01 Jun 1998: - now returns 0 for condition FALSE
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now can analyze an entire string
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isdigit.pro)


ISGRAPH (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISGRAPH (function)

 PURPOSE:
        IDL analog to the 'isgraph' routine in C.  Locates all
        graphics characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISGRAPH( S ) 

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are graphics characters.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        Graphics characters are printing characters (i.e. they can be
        seen on the screen or on a printout) but EXCLUDE the 
        space ( ' ' ) character.

 EXAMPLE:
        print, isgraph( 'ABCD !#~%' )
          1 1 1 1 0 1 1 1 1

        print, isgraph( string( 9B ) )  ; horizontal tab
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998  VERSION 1.10
                          - now can analyze an entire string
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isgraph.pro)


ISLOWER (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISLOWER (function)

 PURPOSE:
        IDL analog to the 'islower' routine in C.  Locates all 
        lowercase alphabetic characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISLOWER( S )

 INPUTS:
        S  -> The string to be tested

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are lowercase alphabetic.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLE:
        print, islower( 'abcdefG' )
          1  1  1  1  1  1  0

        print, islower( 'A' )
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze entire strings
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/islower.pro)


ISPRINT (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISPRINT (function)

 PURPOSE:
        IDL analog to the 'isprint' routine in C.  Returns 1 if
        a character is a printable character (including space).

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISPRINT( S )

 INPUTS:
        S -> The string to be tested.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Where RESULT = 1, the corresponding characters in S
                  are printable.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        Printing characters can be seen on the screen (these exclude
        control characters).

 EXAMPLE:
        print, isprint( '!X3d ' )
          1 1 1 1 0

        print, isprint( string( 9B ) )  ; horizontal tab
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998  - now use BYTE function in where statement
                            instead of hardwired constants
        bmy, 02 Jun 1998: VERSION 1.10
                          - now uses ISGRAPH
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isprint.pro)


ISSPACE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISSPACE (function)

 PURPOSE:
        IDL analog to the 'isspace' routine in C.  Locates 
        white space characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISSPACE( S ) 

 INPUTS:
        S  -> The string to be tested.  

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index 
             array that contains as many elements as S has 
             characters.  If S is a single character, then RESULT 
             will be scalar.  Where RESULT = 1, the corresponding 
             characters in S are numeric.

 SUBROUTINES:
        None

 REQUIREMENTS:

 NOTES:
        None

 EXAMPLES:
        PRINT, ISSPACE( '     ' )
            1 1 1 1 1

        PRINT, ISSPACE( 'A' )
            0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: - now use BYTE function in where statement
                            instead of hardwired constants (where
                            possible)
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze an entire string 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isspace.pro)


ISUPPER (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        ISUPPER (function)

 PURPOSE:
        IDL analog to the 'isupper' routine in C.  Locates all 
        uppercase alphabetic characters in a string.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = ISUPPER( S )

 INPUTS:
        S  -> The string to be tested

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The value of the function.  RESULT is an index array
                  that contains as many elements as S has characters. 
                  If S is a single character, then RESULT will be scalar.
                  Uppercase alphabetic characters in S are thus
                  denoted by the condition ( RESULT eq 1 ).

 SUBROUTINES:
        None

 REQUIREMENTS:
        Assumes that the ASCII character set is the character set
        installed on the system.  The byte values will be different
        for other character sets such as EBSDIC.  

 NOTES:
        None

 EXAMPLE:
        PRINT, ISUPPER( 'ABCDEFg' )
          1  1  1  1  1  1  0

        PRINT, ISUPPER( 'a' )
          0

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        bmy, 02 Jun 1998: VERSION 1.10
                          - now can analyze entire strings
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/isupper.pro)


REPLACE_TOKEN (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        REPLACE_TOKEN (function)

 PURPOSE:
        Replaces occurrences of tokens with text. Can also
        be used to expand wildcards with a name list.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = REPLACE_TOKEN( STR, TOKEN, TEXT, [, Keywords ] )

 INPUTS:
        STR -> The string to be searched for tokens. This must be
             a scalar string.
 
        TOKEN -> A string or string array containing the token text
             *OR* a structure. If TOKEN is a structure, the tag
             names will be used as Tokens and the tag values will
             be converted to string and used as TEXT.  TOKEN is 
             case-insensitive and will always be used as uppercase.

        TEXT -> A string or string array containing the replacement 
             text. TEXT may be some other type than string on input. 
             In this case it will be returned as string and formatted 
             according to the optional FORMAT keyword.  If TOKEN is 
             provided as a structure, TEXT will return the (formatted)
             tag values as strings.  TOKEN and TEXT must have the same 
             number of elements with one exception: If TOKEN contains 
             only one element while TEXT is an array, the result will 
             be a string array where each string has TOKEN replaced 
             with the corresponding TEXT value (wildcard replacement). 
             [see example 7]

 KEYWORD PARAMETERS:
        DELIMITER  -> The delimiter character for TOKEN.  Default is 
             '%'.  The delimiter will be automatically appended to the
             beginning and end of TOKEN if not already there.

        COUNT -> Number of tokens that were replaced. If TOKEN has 
             more than one element or tag, COUNT will be an integer 
             array.

        VERBOSE -> Will print a warning message if no tokens are found.

        FORMAT -> A string or string array containing format 
            specifications for each element of TEXT or each tag of 
            the TOKEN structure. If FORMAT contains only one element, 
            this will be used throughout. For wildcard replacement, 
            the default format is I14 (number will be trimmed).

        TFORMAT -> (type format) If TOKEN is provided as a structure, 
            it may contain data of various types. You can use TFORMAT 
            to specify a format code for each data type (see IDL SIZE
            function) instead of each tag number as with the FORMAT 
            keyword. TFORMAT should contain at least 6 elements to 
            allow formatting of double precision data, or 8 elements 
            if you want to output complex data.

 OUTPUTS:
        RESULT -> String with replaced text.  If TOKEN is a single 
            string and TEXT is an array, then the result is an array 
            with N(text) elements.  In case of errors, an empty string
             is returned.

 SUBROUTINES:
        External Subroutines Used:
        ========================================
        CHKSTRU (function)   STRRIGHT (function)
 
 REQUIREMENTS:
        None

 NOTES:
        (1) The original input string (STR) is not altered.

        (2) REPLACE_TOKEN will search for and replace multiple
            occurrences of the same token in the input string (STR).

        (3) Use DELIM='' for wildcard replacement.

        (4) If no tokens are found in the input string, then
            REPLACE_TOKEN returns the original input string (STR)
            as the value of the function.  

        (5) The use of structures for TOKEN allows for different
            data types.

 EXAMPLE:
        (1)
        STR     = 'Hello, My Name is %NAME% and %NAME%.'
        NEWSTR  = REPLACE_TOKEN( Str, 'NAME', 'Robert' )
        PRINT, NEWSTR
           Hello, my name is Robert and Robert.

             ; Replace multiple tokens in the input string

        (2) 
        STR   = 'His name is %NAME% and he lives in %STREET%, %CITY%'
        TOKEN = { NAME   : 'Henry', $
                  STREET : '29 Oxford St.', $
                  CITY   : 'Cambridge, MA',   $
                  ZIP    : '02138' }
        PRINT, REPLACE_TOKEN( STR, TOKEN )
           His name is Henry and he lives in 
           29 Oxford St., Cambridge, MA
           
           ; Use a structure to replace several items at once
           ; (Note: ZIP code is not used!)

        (3) 
        STR = 'His name is NAME and he lives in STREET, CITY'
        PRINT, REPLACE_TOKEN( STR, TOKEN, DELIM='' )
           His Henry is Henry and he lives in ...

             ; Use of an empty delimiter (same TOKEN as above)
             ; (Exercise: what went wrong ?)

        (4) 
        STR = 'The date is 2003/01/01.'
        PRINT, REPLACE_TOKEN( STR, '2003', 2005', DELIM='' )
           The date is 2005/01/01.

             ; Another use of an empty delimiter
             ; (very useful for switching dates/times!!!)

        (5) 
        STR    = 'She earns %Salary%.'
        FORMAT = '("$",g0.10)'
        PRINT, REPLACE_TOKEN( STR, 'Salary', 39000., FORMAT=FORMAT )
           She earns $39000.

             ; Use of FORMAT

        (6) 
        STR     = '%Name% earns %Salary%.'
        VAL     = { NAME   : 'Sally', $
                    SALARY : 39000. }
        TFORMAT = [ '(A)','','','','("$",g0.10)','("$",g0.10)' ]
             ; (format codes for string, float and double)

        PRINT, REPLACE_TOKEN( STR, VAL, TFORMAT=TFORMAT )
           Sally earns $39000.

             ; Use of TFORMAT

        (7) 
        FILEMASK = '~/data/cruise$$.dat'
        CRUISES  = indgen(10)+1   
        PRINT, REPLACE_TOKEN( FILEMASK, '$$', $
                              CRUISES, DELIM='', FORMAT='(I2.2)' )
           ~/data/cruise01.dat 
           ~/data/cruise02.dat ...
           ~/data/cruise10.dat

             ; Wildcard replacement

 MODIFICATION HISTORY:
        bmy, 23 Sep 1998: VERSION 1.00
        bmy, 24 Sep 1998: - added VERBOSE keyword and improved comments
        mgs, 24 Sep 1998: - improved error handling
                          - TOKEN and TEXT may now be arrays
                          - *or* TOKEN may be a structure
                          - TEXT is trimmed
                          - added FORMAT and TFORMAT keywords
        mgs, 23 Dec 1998: - added wildcard (isarray) functionality
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments

(See /n/home09/ryantosca/IDL/gamap2/strings/replace_token.pro)


RSEARCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        RSEARCH

 PURPOSE:
        Wrapper for routines STRPOS and RSTRPOS.  
        Needed for backwards compatibility for GAMAP users 
        who are running versions of IDL prior to 5.2.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = RSEARCH( STR, PATTERN )

 INPUTS:
        STR -> The string to be searched.  

        PATTERN -> The pattern to search for in STR.

 KEYWORD PARAMETERS:
        None
           
 OUTPUTS:
        RESULT -> Character index where PATTERN is found in STR

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        STR = "This is a test: Hello!"
        PRINT, RSEARCH( STR, 'test:' )
          10
             ; Location where PATTERN is found in STR

 MODIFICATION HISTORY:
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
        bmy, 14 Apr 2005: TOOLS VERSION 2.04
                          - Now uses CALL_FUNCTION to call STRPOS
                            and RSTRPOS so as to avoid bugs at
                            compile-time 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/rsearch.pro)


STR2BYTE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STR2BYTE (function)

 PURPOSE:
        Convert a string into a byte vector of a given length
        for output in binary data files.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        BSTR = STR2BYTE( STRING [, LENGTH ] )

 INPUTS:
        STRING -> The string to be converted

        LENGTH -> Length of the byte vector. Default is to use the 
            length of the string. If LENGTH is shorter, the string
            will be truncated, if it is longer, it will be filled 
            with blanks (32B).

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        BSTR -> A byte vector of the specified length

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        OPENW, LUN, 'TEST.DAT', /F77_UNFORMATTED, /GET_LUN
        WRITEU, LUN, STR2BYTE( 'Test string', 80 )
        FREE_LUN, LUN

             ; write a 80 character string into a binary file

 MODIFICATION HISTORY:
        mgs, 24 Aug 1998: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/strings/str2byte.pro)


STRBREAK

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRBREAK

 PURPOSE:
        Wrapper for routines STRSPLIT and STR_SEP.  
        Needed for backwards compatibility for GAMAP users 
        who are running versions of IDL prior to 5.2.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = STRBREAK( STR, SEPARATOR, _EXTRA=e )

 INPUTS:
        STR -> The string to be separated.  

        SEPARATOR -> The separating character.

 KEYWORD PARAMETERS:
        None
           
 OUTPUTS:
        RESULT = Array of sub-strings, separated by the character 
             passed as SEPARATOR

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        (1)
        Str    = 'Hello   , My     , Name    , is    ,  Slim ,   Shady  '
        NewStr = StrBreak( Str, ',' )

             ; Separates the string using the comma as the separator.

 MODIFICATION HISTORY:
        bmy, 17 Jan 2002: TOOLS VERSION 1.50
        bmy, 17 Jan 2003: TOOLS VERSION 1.52
                          - now use CALL_FUNCTION to call both STRSPLIT 
                            and STR_SEP functions for backwards compatibility
        bmy, 14 Oct 2003: TOOLS VERSION 1.53
                          - deleted obsolete code
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/strbreak.pro)


STRCHEM (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRCHEM (function)

 PURPOSE:
        Superscripts or subscripts numbers and special
        characters ('x', 'y') found in strings containing 
        names of chemical species.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = STRCHEM( STR [,keywords] )

 INPUTS:
        STR -> The input string containing the name of the
             chemical species (e.g. 'NOx', 'H2O', CxO2, etc, ) 

 KEYWORD PARAMETERS:
        /SUB -> Will cause numbers and special characters to 
             be subscripted.  This is the default.

        /SUPER -> Will cause numbers and special characters to
             be superscripted.

        SPECIALCHARS -> a string with characters that shall be sub- 
             or superscripted. Defaults are '0123456789xyXY' for
              /SUB and '+-0123456789' for /SUPER

        PROTECT -> internal keyword used to protect certain characters
             from being super or subscripted. May be useful to
             circumvent troubles. See example below. 

        /TRIM -> perform a strtrim( ,2) on the result

 OUTPUTS:
        RESULT -> String with formatting characters included

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        (1)
        PRINT, STRCHEM( 'C2H5O2 [pptv]' )
          C!l2!nH!l5!nO!l2!n [pptv]"

        (2)
        PRINT, STRCHEM( STRCHEM('NH4+',/sub), /SUPER, SPECIAL='+-' )
          NH!l4!n!u+!n.

        (3)
        S0      = '(H2O2)2'                   ; supposed to be H2O2 squared
        PROTECT = STRLEN( s0 )-1              ; protect last character
        S1      = STRCHEM(S0,PROTECT=PROTECT)
        S2      = STRCHEM(S1,/SUPER,PROTECT=PROTECT)
        PRINT, S1, '->', S2
          (H!l2!nO!l2!n)2->(H!l2!nO!l2!n)!u2!n

             ; without protect the "square" would have been subscripted

 MODIFICATION HISTORY:
        bmy, 01 Jun 1998: VERSION 1.00
        mgs, 02 Jun 1998: VERSION 1.10 - rewritten
        mgs, 11 Jun 1998: - removed IS_ION keyword
                          - changed default specialchars for SUPER
        mgs, 22 Sep 1998: - added TRIM keyword
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments, cosmetic changes

(See /n/home09/ryantosca/IDL/gamap2/strings/strchem.pro)


STRDATE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRDATE (function)

 PURPOSE:
        Format a "standard form" date string 

 CATEGORY:
        Date & Time, Strings

 CALLING SEQUENCE:
        RESULT = STRDATE( [ DATE ] [, Keywords ] )

 INPUTS:
        DATE -> (OPTIONAL) Either a up to 6 element array containing 
            year, month, day, hour, minute, and secs (i.e. the format 
            returned from BIN_DATE) or a structure containing year, 
            month, day, hour, minute, seconds (as returned from 
            TAU2YYMMDD) or a date string in "standard" format as 
            returned by SYSTIME(0).  If DATE is omitted, STRDATE will 
            automatically return the current system time. 

 KEYWORD PARAMETERS:
        /SHORT -> omit the time value, return only date

        /SORTABLE -> will return 'YYYY/MM/DD HH:MM' 

        /EUROPEAN -> will return 'DD.MM.YYYY HH:MM'

        IS_STRING -> Indicates that DATE is a date string 
            rather than an integer array.  This keyword is now 
            obsolete but kept for compatibility.

 OUTPUTS:
        RESULT -> A date string formatted as 'MM/DD/YYYY HH:MM'.
            If SHORT flag is set, the format will be 'MM/DD/YYYY'

 SUBROUTINES:
        External Subroutines Required:
        ==============================
        DATATYPE (function)

 REQUIREMENTS:
        None

 NOTES:
        (1) /EUROPEAN and /SORTABLE will have effect of 
            /SORTABLE but with dots as date Seperators.

 EXAMPLES:
        (1)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ] )
           01/01/2001 12:30
             ; Date string for 2001/01/01 12:30 in USA format

        (2)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /EUROPEAN )
           01.01.2001 12:30
             ; Date string for 2001/01/01 12:30 in European format

        (3)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE )
           2001/01/01 12:30
             ; Date string for 2001/01/01 12:30 in YYYY/MM/DD format

        (4)
        PRINT, STRDATE( [ 2001, 01, 01, 12, 30, 00 ], /SORTABLE, /SHORT )
           2001/01/01
             ; Date string for 2001/01/01 w/o hours and minutes

        (5)
        RESULT = TAU2YYMMDD( 144600D )
        PRINT, STRDATE( RESULT, /SORTABLE )
           2001/07/01 00:00
             ; Use TAU2YYMMDD to convert a TAU value (in this case
             ; for July 1, 2001) to a structure.  Then pass the
             ; structure to STRDATE to make a string.

 MODIFICATION HISTORY:
        mgs, 11 Nov 1997: VERSION 1.00
        mgs, 26 Mar 1998: VERSION 1.10 
                          - examines type of DATE parameter 
                            and accepts structure input.
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Renamed /GERMAN to /EUROPEAN
                          - Updated comments, cosmetic changes
                          - Now uses function DATATYPE

(See /n/home09/ryantosca/IDL/gamap2/date_time/strdate.pro)


STRPAD

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRPAD

 PURPOSE:
        This function returns the source string padded with leading
        and/or trailing white-space characters.

 CATEGORY:
        Strings

 CALLING SEQUENCE:

        Result = STRPAD( Source, Length [, Pos] )

 INPUTS:
        Source:   A string or number you want padded with white-space
                  characters.

        Length:   The total length of the returned padded string.

 OPTIONAL INPUTS:

        Pos:      Position of the Source string within the returned
                  padded string. [0=Default]

 OUTPUTS:
        The source parameter is returned as a string with leading
        and/or trailing white-space characters.

 RESTRICTIONS:
        The Length and Pos parameters must be in the range [0-255].

 EXAMPLE:
        Let's say you want 'bob' to have a length of 10 characters
        with spaces padded after 'bob':

        bob10 = STRPAD( 'bob', 10 )

        Or if you want 'bob' to be at the end:

        bobend= STRPAD( 'bob', 10, 7 )

 MODIFICATION HISTORY:
        Written by:    Han Wen, December 1994.

(See /n/home09/ryantosca/IDL/gamap2/strings/strpad.pro)


STRREPL (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRREPL (function)

 PURPOSE:
        Replace all occurences of one character in a string with 
        another character. The character to be replaced can either 
        be given as string of length 1 or as an index array
        containing the character positions (see strwhere).  This 
        function also works for string arrays.

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = STRREPL( STR, FROMCHAR, TOCHAR [,/IGNORECASE] )

 INPUTS:
        STR -> the string to be changed

        FROMCHAR -> either: a string of length 1 (the character 
             to be replaced) or: an index array with the character 
             positions

        TOCHAR -> replacement character

 KEYWORD PARAMETERS:
        IGNORECASE -> if set, fromchar will be treated 
             case-insensitive (only if fromchar is a character)

        FOLD_CASE -> same thing but following IDL naming 
             (e.g. StrMatch)

 OUTPUTS:
        RESULT -> A string of same length as the input string
             with the text replaced

 SUBROUTINES:

 REQUIREMENTS:

 NOTES:
        Uses SIZE(/TYPE) available since IDL 5.2

 EXAMPLES:
        (1)
        UFILE = '/usr/local/idl/lib/test.pro'
        WFILE = 'c:' + strrepl(ufile,'/','\')
        PRINT, WFILE
        ;  c:\usr\local\idl\lib\test.pro

             ; Convert a Unix filename to Windows

        (2)
        A      = 'abcdabcdabcd'
        INDEX  = [ strwhere(a,'a'), strwhere(a,'b') ] > 0
        PRINT, STRREPL( a, index, '#' )
           ##cd##cd##cd

             ; Use with index (uses strwhere function)

 MODIFICATION HISTORY:
        mgs, 02 Jun 1998: VERSION 1.00
        mgs, 24 Feb 2000: - rewritten
                          - now accepts character argument
                          - added IGNORECASE keyword
        mgs, 26 Aug 2000: - changed copyright to open source
                          - added FOLD_CASE keyword
        bmy, 28 Oct 2003: VERSION 1.01
                          - Need to test if FROMCHAR is a character
                            or a byte type.  This will allow STRREPL
                            to replace non-printable ASCII characters
                            such as Horizontal TAB ( BYTE(9B) ).  
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/strings/strrepl.pro)


STRRIGHT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRRIGHT

 PURPOSE:
        Return right subportion from a string

 CATEGORY:
        Strings 

 CALLING SEQUENCE:
        RESULT = STRRIGHT( STRING [,nlast] )

 INPUTS:
        STRING -> the string to be searched

        NLAST -> the number of characters to be returned. 
             Default is 1. If NLAST is ge strlen(STRING), 
             the complete string is returned.

 KEYWORD PARAMETERS:
        None

 OUTPUTS:
        RESULT -> The portion of NLAST characters of STRING 
             counted from the back.

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        IF ( STRRIGHT( PATH ) NE '/' ) THEN PATH = PATH + '/'

             ; Add a slash to a directory name if necessary

 MODIFICATION HISTORY:
        mgs, 19 Nov 1997: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - Updated comments

(See /n/home09/ryantosca/IDL/gamap2/strings/strright.pro)


STRSCI (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRSCI (function)

 PURPOSE:                                                 
        Given a number, returns a string of that number in 
        scientific notation format ( e.g. A x 10  )

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        RESULT = STRSCI( DATA  [, Keywords ] )

 INPUTS:
        DATA -> A floating point or integer number to be
             converted into a power of 10.

 KEYWORD PARAMETERS:
        FORMAT -> The format specification used in the string
             conversion for the mantissa (i.e. the "A" of 
             "A x 10^B").  Default is '(f12.2)'.  

        /POT_ONLY -> Will return only the "power of 10" part of 
             the string (i.e. the "10^B").  Default is to return 
             the entire string (e.g. "A x 10^B" )

        /MANTISSA_ONLY -> return only mantissa of the string

        /SHORT -> return 10^0 as '1' and 10^1 as '10'

        /TRIM -> don't insert blanks (i.e. return Ax10^B)

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        This function does not "evaluate" the format statement thoroughly
        which can result in somewhat quirky strings. Example:
        print,strsci(-9.999) results in -10.0x10^0 instead of -1.0x10^1.

        Need a better symbol than the 'x' for the multiplier...

 EXAMPLE:
        Result = STRSCI( 2000000, format='(i1)' )
        print, result                
        ;                                                     6
        ;     prints 2 x 10!u6!n, which gets plotted as 2 x 10 
        
        Result = STRSCI( -0.0001 )
        print, result
        ;                                                            4
        ;     prints -1.00 x 10!u-4!n, which gets plotted as 1.00 x 10

        Result = STRSCI( 0d0, format='(f13.8)' )
        print, result
        ;
        ;     prints, 0.00000000
 

 MODIFICATION HISTORY:
        bmy, 28 May 1998: INITIAL VERSION
                          - now returns string of the form A x 10
        mgs, 29 May 1998: - bug fix: now allows negative numbers
                          - keyword MANTISSA_ONLY added
                          - default format changed to f12.2
        bmy, 02 Jun 1998: - renamed to STRSCI 
                            ("STRing SCIentific notation")
        mgs, 03 Jun 1998: - added TRIM keyword
        mgs, 22 Sep 1998: - added SHORT keyword
                          - modified handling of TRIM keyword
        mgs, 24 Sep 1998: - bug fix with SHORT flag
  bmy & mgs, 02 Jun 1999: - now can handle DATA=0.0 correctly
                          - updated comments
        mgs, 03 Jun 1999: - can now also handle values lt 1 ;-)
                          - and doesn't choke on arrays
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
                          - updated comments

(See /n/home09/ryantosca/IDL/gamap2/strings/strsci.pro)


STRSIZE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRSIZE

 PURPOSE:
        Given a string argument and the character size, returns the
        # of characters that can fit w/in the horizontal or vertical
        extent of a plot window.

 CATEGORY:
        Plotting, Strings

 CALLING SEQUENCE:
        RESULT = STRSIZE( STRARG, CHARSIZE [, Keywords ] )

 INPUTS:
        STRARG -> A string of characters.

        CHARSIZE -> The size of each character.  1.0 is normal 
             size, 2.0 is double size, etc.
 
 KEYWORD PARAMETERS:
        /Y -> Set this switch to compute the number of characters
             that can fit along the vertical extent of the plot.

 OUTPUTS:
        None

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        OPEN_DEVICE, WINPARAM=[ 0, 800, 600 ]
        PRINT, STRSIZE( 'Hello', 3 )
           80.0000
           
             ; Computes the # of characters of size 3 
             ; that can fit in the plot window


 MODIFICATION HISTORY:
        bmy, 10 Oct 2006: VERSION 1.00
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/plotting/strsize.pro)


STRWHERE (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
        STRWHERE  (function)

 PURPOSE:
        return position *array* for occurence of a character in
        a string

 CATEGORY:
        Strings

 CALLING SEQUENCE:
        POS = STRWHERE( STR, SCHAR [,COUNT] )

 INPUTS:
        STR -> the string

        SCHAR -> the character to look for

 KEYWORD PARAMETERS:
        none.

 OUTPUTS:
        COUNT -> (optional) The number of matches that were found 

        POS -> The function returns an index array similar to the 
             result of the where function

 SUBROUTINES:
        None

 REQUIREMENTS:
        None

 NOTES:
        None

 EXAMPLE:
        IND = STRWHERE( 'abcabcabc', 'a' )

        ; returns [ 0, 3, 6 ]

 MODIFICATION HISTORY:
        mgs, 02 Jun 1998: VERSION 1.00
        bmy, 30 Jun 1998: - now returns COUNT, the number 
                            of matches that are found (this is
                            analogous to the WHERE command)
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/strings/strwhere.pro)


STR_SIZE

[Previous Routine] [List of Routines]
 NAME:
  STR_SIZE

 PURPOSE:

  The purpose of this function is to return the proper
  character size to make a specified string a specifed
  width in a window. The width is specified in normalized
  coordinates. The function is extremely useful for sizing
  strings and labels in resizeable graphics windows.

 CATEGORY:
  Strings, Graphics

 CALLING SEQUENCE:

  thisCharSize = STR_SIZE(thisSting, targetWidth)

 INPUTS:

  thisString:  This is the string that you want to make a specifed
     target size or width.

 OPTIONAL INPUTS:

  targetWidth:  This is the target width of the string in normalized
     coordinates in the current graphics window. The character
     size of the string (returned as thisCharSize) will be
     calculated to get the string width as close as possible to
     the target width. The default is 0.25.

 KEYWORD PARAMETERS:

  INITSIZE:  This is the initial size of the string. Default is 1.0.

  STEP:   This is the amount the string size will change in each step
     of the interative process of calculating the string size.
     The default value is 0.05.

 OUTPUTS:

  thisCharSize:  This is the size the specified string should be set
     to if you want to produce output of the specified target
     width. The value is in standard character size units where
     1.0 is the standard character size.

 EXAMPLE:

  To make the string "Happy Holidays" take up 30% of the width of
  the current graphics window, type this:

               XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
        CHARSIZE=STR_SIZE("Happy Holidays", 0.3)

 MODIFICATION HISTORY:

  Written by: David Fanning, 17 DEC 96.
  Added a scaling factor to take into account the aspect ratio
     of the window in determing the character size. 28 Oct 97. DWF

(See /n/home09/ryantosca/IDL/gamap2/strings/str_size.pro)