Miscellaneous Procedures                      pro/misc         December 2001

The procedures in this directory are general utility procedures that do not
involve astronomy.   They are included here either because they are required
by an astronomy-related procedure, or because they are thought to be of 
sufficient general interest.

The procedure ASTROLIB defines the non-standard system variables !TEXTOUT,
!TEXTUNIT and !DEBUG which some Astronomy Library procedures require to be 
defined before they can compile.

The function TRIM() is kept here for backwards compatibility but is
not used by any other AstroLib procedure, and conflicts with a procedure of the
same name in the IUE Library.

Similarly DATATYPE() is not used in any other AstroLib procedure because it has
diverged from the version of DATATYPE() in the JHU/APL Library

The procedures FIND_ALL_DIR and CONCAT_DIR were originally from the Solar 
Library ( http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/system/ ) but do not
contain the full capabilities of the Solar Library versions.    (This is because
the Solar Library versions call external procedures not in the IDL Astro 
Library.)

ASTROLIB - Add the non-standard system variables in use in the IDL
           Astronomy User's Library
BOOST_ARRAY - Append one array onto another, adjusting dimensions if necessary
BREAK_PATH() - break up a !PATH-like string into individual directories
BSORT() - Like the IDL SORT function but subscript order is maintained when
        value are equal -- like a bubble sort.
CHECKSUM32 - Compute the 32bit checksum of an array (ones-complement arithmetic)
CIRRANGE - Force an angle to be in the range 0 to 2*!PI (or 0 to 360).
CONCAT_DIR - concatenate directory and file name for current OS
CONV_UNIX_VAX - Convert IEEE datatype to VMS datatypes
CONV_VAX_UNIX() - Convert Vax datatypes to Unix using proper byteswapping
DATATYPE() - Return the datatype of an IDL variable as a string 
DEF_DIRLIST - Define a directory list using SETENV or SETLOG
DELVARX - Delete an IDL variable; like DELVAR but works at any calling level
DETABIFY() - Replace tabs in a character string by equivalent number of spaces
EXPAND_TILDE() - Expand the tilde in Unix directory names
F_FORMAT() - Find the "best" F format to display an array of REAL*4 numbers.
FDECOMP - Decompose a file name (Disk + Directory + Name + Extension + Version)
FIND_ALL_DIR() - Finds all directories under a specified directory.
FIND_WITH_DEF - Search for files with default path and extension
FINDPRO - Find all occurrences of a procedure in one's !PATH
FORPRINT -Print a set of vectors by looping over each index value
FSTRING() - Wrapper to STRING function to get around 1024 element formatted limit
GETFILES -Interactively specify a list of file numbers.
GETLOG() - Format the input name as a logical directory in the host OS
GETOPT() -  Parse a user supplied string into numeric value(s).
GETPRO -  Search !PATH directory for a procedure and copy into user's directory
GETTOK() -  Extract a string up to a specified character.
GETWRD() -  Get specified item (word) from a string (in /jhuapl)
HGREP -  Find a substring in a FITS header (or any other string array)
HOST_TO_IEEE - Convert IDL variable from host machine bit order to IEEE
HPRINT -  Pretty terminal display of a FITS header (or other string array)
IEEE_TO_HOST - Convert IDL variable from IEEE bit order to host machine
ISARRAY() - Determine if an IDL variable is an array (in /jhuapl)
IS_IEEE_BIG() - Determine if the host machine is IEEE big endian 
LIST_WITH_PATH() - Search for files within specified directory path
MAKE_2D - Change from 1-D indexing to 2-D indexing
MATCH -   Find the subscripts where the values of two vectors match.
MINMAX() -  Return the min and max of an array in an 2 element vector
MRD_SKIP - Skip a number of bytes from current location in a file or Unix pipe
N_BYTES() - Return the number of bytes in an IDL variable
NINT() - Like intrinsic ROUND() function but returns integer instead of long
NULLTRIM() -Delete all characters after, and including, the the first null
          byte(0).  Called by TAB_PUT.
NUMLINES() - Return the number of lines in a file
ONE_ARROW - Draw an arrow labeled with a single character
ONE_RAY - Draw a ray by specifying starting point, angle, and length
ORDINAL() - Return the English equivalent of ordinal numbers, i.e. '1st','2nd'
OSFCNVRT() - Format the input as a logical name in the host operating system
POLREC - Convert from polar to rectangular coordinates (in /jhuapl)
PRODUCT() - Return the product of all the elements of an array.
QGET_STRING() - Read a string (eg. password) from the keyboard without echoing it
RDFLOAT - Quickly read an ASCII file with columns of data into IDL vectors
READ_KEY() - Like GET_KBRD but returns a code for escape sequences.
READCOL - Read a file of free-format  ASCII data into IDL vectors
READFMT - Quickly read a file of fixed-format ASCII data into IDL vectors
RECPOL - Convert from rectangular to polar coordinates (in /jhuapl)
REMCHAR - Remove all appearances of a character from a string.
REM_DUP() - Remove duplicate values from a vector.
REMOVE -  Contract a vector or up to 8 vectors by removing specified
          elements.
REPCHR() -  Replace all occurrences of one character by another (in /jhuapl)
REPSTR() -  Replace all occurrences of one substring in a string by another.
SCREEN_SELECT - Allow user to interactively select from a list of strings
                Used by the database software
SELECT_O - VT100 terminal branch of SCREEN_SELECT
SELECT_W - IDL widget branch of SCREEN_SELECT.
SPEC_DIR() - Complete specification of a file name using default disk & directory
STORE_ARRAY - Insert one array into another, adjusting dimensions if necessary
STREBCASC() - Convert an EBCDIC string scalar or vector to its ASCII equivalent
STR_INDEX - Get all indicies of a substring within a string
STRN() - Convert a number to a string and remove padded blanks.
STRNUMBER()- Determine whether a string is a valid numeric value.
TEXTOPEN - Open a file for text output as specified by !TEXTOUT
           Controls the print output device for many procedures.
TEXTCLOSE - Close a file that had been opened by TEXTOPEN.
TO_HEX()    - Translate a decimal integer to a hex string.  Called by AIPSNAME.
TRIM() - Convert numbers to strings, without trailing zeros.
VALID_NUM() - Determine if a string is a valid number (cf. STRNUMBER)
VECT() - Display a set of numbers to a string with delimiters
WHERENAN() - Find points equal to IEEE NaN (not a number) values
WHERE_NEGZERO() - Find locations of IEEE -0.0 values
ZPARCHECK - Check the type and size of a parameter