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
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)