This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Apr 22 10:32:07 1999.
FUNCTION:
DATESEC
DESCRIPTION:
function to parse out a date string of either the form [YY]YY-MM-DD
(e.g. '1989-10-1' or '89-10-1), DD/MM/YY (e.g. '1/10/89'), DD MMM YY
(e.g. '1 Oct 89' or '1 OCT 89', case ingnored) or YYYY/MM/DD
(e.g. 1989/10/01, where the first field is greater than 31). The
RETURN value is double float in seconds since 1 Jan 1970, 00:00 UT.
USAGE (SAMPLE CODE FRAGMENT):
; seconds since 1970
string_date = '21 Mar 91'
; convert to string
seconds_date = datesec(string_date)
; print it out
PRINT, seconds_date
--- Sample output would be
6.6951720e+08
NOTES:
If conversion fails, this function returns -1.
For the forth input format to work (YYYY/MM/DD), the year
specified must be greater than 31, otherwise the DD/MM/YY
format assumed.
Note that NO combination of of input formats will work. Also, all
three fields must be present.
If any of the fields is to large then a carry operation will occur.
i.e. 34/13/89 would come out to year 90, month 2, day 3.
If input seconds is an array, then an array of
N_ELEMENTS(inputs vals) of date strings and remainders will be returned.
REVISION HISTORY:
@(#)datesec.pro 1.6 17 Aug 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Jan. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datesec.pro)
FUNCTION:
DATESEC_DOY
DESCRIPTION:
take args for year and day of year and return
(double float) seconds since 1 Jan 1970, 00:00 UT.
USAGE:
print, datesec_doy(75, 134)
gives result:
1.6925760e+08
NOTES:
does not handle years past 1999; year must be two digit.
REVISION HISTORY:
@(#)datesec_doy.pro 1.1 04 Jun 1995
written by Ken Bromund, Space Sciences Lab, Berkeley. May, 1991
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datesec_doy.pro)
FUNCTION:
DATESEC_VAR
DESCRIPTION:
function to return seconds since 1 Jan 1970, 00:00 UT corresponding
to beginning of given day.
USAGE (SAMPLE CODE FRAGMENT):
; seconds since 1970
day = 21
month = 3
year = 91
; convert to string
seconds_date = datesec_var(day, month, year)
; print it out
PRINT, seconds_date
--- Sample output would be
6.6951360e+08
NOTES:
If conversion fails, this function returns -1.
If any of the fields is to large then a carry operation will occur.
i.e. 34/13/89 would come out to year 90, month 2, day 3.
If inputs are arrays, then an array of
N_ELEMENTS(inputs vals) of times will be returned
REVISION HISTORY:
@(#)datesec_var.pro 1.2 07 Jun 1995
Originally written by Ken Bromund, University of
California at Berkeley, Space Sciences Lab. May, '92
made to give results equivalent to datesec by Jon Loran
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datesec_var.pro)
FUNCTION:
DATESTRUCT
DESCRIPTION:
function to parse out a date string of either the form DD-MM-YY
(e.g. '1-10-89'), DD/MM/YY (e.g. '1/10/89'), DD MMM YY (e.g.
'1 Oct 89' or '1 OCT 89', case ingnored) or YYYY/MM/DD (e.g.
1989/10/01, where the year is greater than 31).
The return value is a structure of the format:
{date_str $
,year: 1970 $ ; year component of the date
,month: 01 $ ; month component of the date
,monthday: 01 $ ; day of month component of the date
,secs: 0.D $ ; seconds since 1 Jan 1970 00:00:00
,valid: 1 $ ; contents are valid
}
USAGE (SAMPLE CODE FRAGMENT):
; seconds since 1970
string_date = '21 Mar 91'
; convert to string
date_struct = datestruct(string_date)
; print it out
PRINT, date_struct
--- Sample output would be
{1991, 03, 21, 6.6951720e+08, 1}
NOTES:
If conversion fails, this function returns a date_str with the valid
tag set to 0.
For the forth input format to work (YYYY/MM/DD), the year
specified must be greater than 31, otherwise the DD/MM/YY
format assumed.
Note that NO combination of of input formats will work. Also, all
three fields must be present.
If any of the fields is to large then a carry operation will occur.
i.e. 34/13/89 would come out to year 90, month 2, day 3.
If input seconds is an array, then an array of
N_ELEMENTS(inputs vals) of dat estrings and remainders will be
returned.
REVISION HISTORY:
@(#)datesec.pro 1.2 04 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. June. '95
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datestruct.pro)
FUNCTION:
DATETIMESEC_DOY
DESCRIPTION:
function to return seconds since 1/1/1970 00:00 UT, from date and
time given as day, month, year, hour, minute, second, millisecond.
USAGE (SAMPLE CODE FRAGMENT):
; set up a date and time (21 Mar '91, 00:01:01.000)
doy = 80
year = 91
hour = 0
min = 1
sec = 1
msc = 0
; convert to seconds
sec_date_time = datetimesec_doy(year, doy, hour, min, sec, msc)
; print it out
PRINT, sec_date_time
--- Sample output would be
669517261
NOTES:
If any of the fields are are out of range, the value will be carried.
e.g. given date and time of 31/12/90, 25:01:00.1001, this will be
converted to 1/1/91, 01:01:01: 001
If any of the input values are negitive, this is an error and -1 will
This function can return seconds of days, or seconds since 1970 only
by calling it with dates or times set to zero.
If input values are arrays, then an array of N_ELEMENTS(inputs vals)
of date strings and remainders will be returned. The number of
array elements for all input parameters must be the same
REVISION HISTORY:
@(#)datetimesec_doy.pro 1.1 04 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Mar. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datetimesec_doy.pro)
FUNCTION:
DATETIMESEC_VAR
DESCRIPTION:
function to return seconds since 1/1/1970 00:00 UT, from date and
time given as day, month, year, hour, minute, second, millisecond.
USAGE (SAMPLE CODE FRAGMENT):
; set up a date and time (21 Mar '91, 00:01:01.000)
day = 21
month = 3
year = 91
hour = 0
min = 1
sec = 1
msc = 0
; convert to seconds
sec_date_time = datetimesec_var(day, month, year, hour, min, sec, msc)
; print it out
PRINT, sec_date_time
--- Sample output would be
669517261
NOTES:
If any of the fields are are out of range, the value will be carried.
e.g. given date and time of 31/12/90, 25:01:00.1001, this will be
converted to 1/1/91, 01:01:01: 001
If any of the input values are negitive, this is an error and -1 will
This function can return seconds of days, or seconds since 1970 only
by calling it with dates or times set to zero.
If input values are arrays, then an array of N_ELEMENTS(inputs vals)
of date strings and remainders will be returned. The number of
array elements for all input parameters must be the same
REVISION HISTORY:
@(#)datetimesec_var.pro 1.2 20 Jul 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Mar. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/datetimesec_var.pro)
PROCEDURE:
HEAD.PRO
DESCRIPTION:
Procedure to print out the head (first few elements) of an array.
USAGE:
HEAD, input_array, [NUMBER=number-of-initial-elements]
ARGUMENTS:
input_array The array to print.
KEYWORDS:
NUMBER The number if array elements to print.
REVISION HISTORY:
@(#)head.pro 1.1 04 Jun 1995
Originally written by Terry Slocum, University of
California at Berkeley, Space Sciences Lab. Sep. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/head.pro)
FUNCTION:
ISIN.PRO
DESCRIPTION:
Function to return an array of values in array "a" that are inclusive
of array "b". We assume that array's "a" and "b" are of the same type.
If no matchs are found, -1 is returned
USAGE:
result = ISIN (a, b)
ARGUMENTS:
a First array to search
b Second array to search
REVISION HISTORY:
@(#)isin.pro 1.1 04 Jun 1995
Originally written by Jonathan M Loran, University of
California at Berkeley, Space Sciences Lab. Oct. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/isin.pro)
FUNCTION:
MONTHYRFROM
DESCRIPTION:
Function to build an array of strings of the format:
'YR-MN-1'
given a start time in seconds since 1970.
The date in each string increases monotonically, in the specified
number of months increments for the number of strings requested,
from the start time given.
Input parameters are the time to start the strings in seconds
since 1970, Jan 1, 00:00, the number of strings to output, and
the number of months to increment by.
USAGE (SAMPLE CODE FRAGMENT):
; set an array of strings to month and year date representions
date_strings = monthyrfrom(16156800.0,8,2) ; 8 dates, in 2 month
; increments, starting at
; 7 Jul 1970 0:0:0.00
; output result
PRINT, date_strings
--- Sample output would be
70-7-1 70-9-1 70-11-1 70-1-1 70-3-1 70-5-1 70-7-1 70-9-1
NOTES:
The start time in seconds is normally a float type, though
this isn't necessary.
If the input start time is negitive, this is an error, and the string
'ERROR' is returned.
If an array of start times is given, then a two dimensional array
of dimensions (n_dates,N_ELEMENTS(inputs vals)) of stings will
be returned.
the increment can have any sign.
This routine calls the function "SECDATE".
REVISION HISTORY:
@(#)monthyrfrom.pro 1.3 18 Aug 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Feb. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/monthyrfrom.pro)
NAME: notin PURPOSE: Function to return an array of values in array "a" that are exclusive of array "b". We assume that array's "a" and "b" are of the same type. CALLING SEQUENCE: c = notin (a, b) ARGUMENTS: a First array to search b Second array to search SIDE EFFECTS: none INPUTS: two arrays: a and b both of the same type. MODIFICATION HISTORY: @(#)notin.pro 1.1 04 Jun 1995 Written By Jonathan Loran, UCB Feb. 25 '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/notin.pro)
FUNCTION:
SECDATE
DESCRIPTION:
function to return a date string from the number of seconds since
1970, Jan. 1 00:00. Output format is controled by the keyword
FMT. This function will return a string in the format:
FMT=0 YYYY-MM-DD (e.g. "1991-03-21");
FMT NE 0 DD MMM YY (e.g. " 3 Mar 91");
In addition, the remander in seconds of the day are returned through
the remainder formal, which can be used in a subsiquent call to the
function sectime if the full representation of time in date/time is
desired.
USAGE (SAMPLE CODE FRAGMENT):
; seconds since 1970
seconds_date = 6.6951720e+08 ; 21 Mar 91, 01:00:00.000
; convert to string
date_string = secdate(seconds_date,remainder, FMT=0)
; print it out
PRINT, date_string, remainder
--- Sample output would be
1991-03-21, 3600.
KEYWORDS:
FMT Controls the output string format. See description above.
NOTES:
The seconds and remainder parameters should be double precision.
If seconds is given negitive, this is an error and the string 'ERROR' is
returned.
If input seconds is an array, then an array of
N_ELEMENTS(inputs vals) of date strings and remainders will be returned.
Credits: adapted from The C Programming Lanuage, by Kernighan and
Ritchie, 2nd Ed. page 111
REVISION HISTORY:
@(#)secdate.pro 1.4 17 Aug 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Jan. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/secdate.pro)
FUNCTION:
SECOFDAY
DESCRIPTION:
Function to return seconds of a day, given the time in hours, minutes,
seconds and milliseconds.
USAGE (SAMPLE CODE FRAGMENT):
; set up a time (00:01:01.001)
hour = 0.
min = 1.
sec = 1.
msc = 1.
; convert to seconds
seconds = secofday(hour, min, sec, msc)
; print it out
PRINT, seconds
--- Sample output would be
61.001
NOTES:
If input seconds is an array, then an array of N_ELEMENTS(inputs vals)
of date strings and remainders will be returned.
The number of array elements for all input parameters must be the same
REVISION HISTORY:
@(#)secofday.pro 1.2 04 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Jan. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/secofday.pro)
FUNCTION:
SECTIME
DESCRIPTION:
function to return a time string from time of day given in seconds---
Given in imput time in the seconds of the day, this function will
return a string in the format:
HH:MM:SS.MSC
USAGE (SAMPLE CODE FRAGMENT):
; seconds of the day
seconds_day = 43200.00 ; 12 noon
; convert to string
time_string = sectime(seconds_day)
; print it out
PRINT, time_string
--- Sample output would be
12:00:00.000
NOTES:
The seconds parameter should be of a floating point type (i.e float
or double)
If the input is greater than 86400. (24 hours), time will be subtracted
in 24 hour chunks, until the time is less than 24 hours.
If seconds is given negitive, this is an error and the string 'ERROR' is
returned.
If input seconds is an array, then an array of
N_ELEMENTS(inputs vals) of time strings will be returned.
REVISION HISTORY:
@(#)sectime.pro 1.2 30 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Dec. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/sectime.pro)
FUNCTION:
SERIES_COMPRESS.PRO
DESCRIPTION:
Routine to return a series of numbers as a string in a compressed
(abreviated) format. Contiguous series of numbers (n and m, in a
subarray) are displayed as:
n..m
If the series is not contiguous, they are displayed as:
nm
The string delimiter is specified by the user with the delimit
parameter. The series must be a numeric type.
USAGE:
SERIES_COMPRESS, input_array, delimit
ARGUMENTS:
input_array The input series, as an array to compress.
delimit The delimiter to use between values
REVISION HISTORY:
@(#)series_compress.pro 1.1 04 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/series_compress.pro)
FUNCTION:
STRIPPATH
DESCRIPTION:
Function that strips off any directory components from a full
file path, and returns the file name and directory components
seperately in the structure:
{file_cmp_str,file_name:'file',dir_name:'dir'}
This is only implemented for UNIX at this time.
USAGE (SAMPLE CODE FRAGMENT):
; find file component of /usr/lib/sendmail.cf
stripped_file = STRIPPATH('/usr/lib/sendmail.cf')
The variable stripped_file would contain:
stripped_file.file_name = 'sendmail.cf'
stripped_file.dir_name = '/usr/lib/'
NOTES:
This function is only implemented for UNIX at this time. It could
easily be adapted for VMS
It is assumed that the length of the filename component is less than
or equal to 128 characters
This routine cannot distinguish between a file and a directory name
if it occurs in the last component. Therefore, the file_name value
could refer to a subdirectory. To prevent this, directories should
be appended with a / before this rountine is called.
REVISION HISTORY:
@(#)strippath.pro 1.1 04 Jun 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Oct. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/strippath.pro)
PROCEDURE:
TAIL.PRO
DESCRIPTION:
Procedure to print out the tail (last few elements) of an array.
USAGE:
TAIL, input_array, [NUMBER=number-of-final-elements]
ARGUMENTS:
input_array The array to print.
KEYWORDS:
NUMBER The number if array elements to print.
REVISION HISTORY:
@(#)tail.pro 1.1 04 Jun 1995
Originally written by Terry Slocum, University of
California at Berkeley, Space Sciences Lab. Sep. '91
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/tail.pro)
FUNCTION:
TIMESEC
DESCRIPTION:
function to parse out a time string of the form hh:mm:sec.msc.
The return value is in seconds of the day.
USAGE (SAMPLE CODE FRAGMENT):
; set up a time string
time_string = '25:01:01.001'
; convert to seconds
time_seconds = timesec(time_string, carries=nc)
; print it out
PRINT, time_seconds, nc
--- Sample output would be
3661.0010, 1
NOTES:
if the input time is greater than 24 hours, then 24 hours will
subtracted until time is less than 24 hours. The CARRIES keyword
if set, will contain the number of rollovers.
The return value is a double float.
if conversion fails, this functin returns -1.
The input is interpreted in the following way:
1) only the last 2 digits of any field is significant, except
for the case of miliseconds, where only the first 3 digits are
significant. e.g. if the second field is 1160, it will be taken
as 60 for fields other than msc, and taken as 116 for millisecond.
2) if the hour is greater than 23, then 24 is subtracted from it
successivly till it is less than 24. e.g. if the hour field is
73, then it will be set to 1
3) if the min or sec is greater than 60, 60 is subtracted and
the remander is caried over to the hour and min, respectively
4) anything after the msc field will be ignored.
5) input is interpreted from left to right for the hour:min:sec parts
e.g. '03:12' is inturpeted as hour=3, min=12, sec=0 and msc=0.
'03' is taken to mean hour=3 and min = sec = msc = 0, however 1.1
is taken to mean hour=1, msc=100, min=sec=0.
6) everything up to the last two digits before the first colon will
be ignored, if the colon is presant. So a string formed thusly:
'1995/1/31 03:00:00.0' will give the hour=3 and min = sec = msc=0.
7) if there is trailing information in the input string, the
time must contain all fields, and the string must not have
other ':' or '.' characters. This allows times to be pulled
off of strings containing other information.
If input sting is an array, then an array of N_ELEMENTS(inputs val)
of date strings and remainders will be returned.
REVISION HISTORY:
@(#)timesec.pro 1.3 06 Oct 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Nov. '91
Revised to handle arrays of input values, JML, Mar. '92
Revised to implement carry keyword, JML Oct. '95
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/timesec.pro)
FUNCTION:
TIMETICK
DESCRIPTION:
Function to build the anotatation for time axes labeling.
Input parameters are the start and end seconds since 1970, Jan 1,
00:00:00.
The return value is a structure of the format:
{time_tk_str $
,xtickname: STRARR(22) $ ; Actual labels for ticks
,xtickv: FLTARR(22) $ ; Actual tick locations
,xticks: 1 $ ; number of major ticks
,xminor: 1 $ ; number of minor ticks
,xrange: FLTARR(2) $ ; min and max time of plot
,xstyle: 1 $ ; const specifying plot style
}
USAGE (SAMPLE CODE FRAGMENT):
; get the start and end values. Assume time_pts array has been
; sorted appropriately
start_sec = time_pts(0)
end_sec = time_pts(N_ELEMENTS(time_pts)-1)
; now we do the plot
time_setup = timetick(start_sec, end_sec, min_max_flag, offset,
datelab)
PLOT, time_pts-offset, value_pts, _EXTRA=time_setup,
XTITLE='Time UT from: ' + datelab
KEYWORDS:
FMT Controls the format of the dates in the time labels.
If FMT is zero, or is not given, then dates will be given as
95/12/30. If FMT is non-zero, then dates will be given as
30 Dec 95.
DATELABFMT Controls the format of the datelab string. If it's
not set or zero, the datelab string will include the full
date and time for the start of the plot. If it's non-zero,
the datelab string will include only the most significant
portion of the date and time of the start of the plot that is
not included in the actual tick marks.
NOTES:
The returned time_tk_str has tags named so that it can be used
with the special _EXTRA keyword in the call to PLOT or OPLOT.
The offset value that is returned from timetick must be
subtracted from the time-axis data values before plotting.
This is to maintain resolution in the PLOT routines, which use
single precision floating point internally. Remember that if
the CURSOR routine is used to read a cursor position from the
plot, this offset will need to be added back to the time-axis
value to get seconds since 00:00:00 1-1-1970.
The datelab returned parameter gives the most significant part
of the date/time that is not included in the tick labels. It will
be derived from the first tick time. It can then be used in
a title to give the date/time of the start of the data, when the
plot duration is to short for this to be included in the xticks.
if the full date is included in the xticks, datelab will be a
null string.
The parameter min_max_flag determines how the start and end times
for the plot will be calculated. If it greater than or equal to 1,
the start and end times will be fourced to align upon a major
tick mark. Otherwise, the start and end times will be set to
the start_sec and end_sec parameters.
This function only makes sense for linear X-axes, though it
should work with the log case as well.
Be warned that usage of large fonts may cause the time labels
to run into eachother. Time labels can be much wider than normal
numeric labels.
Time plot durations of approximately 10 milliseconds to 20 years
are handled.
If arrays of start and end times are given, then an array
of N_ELEMENTS(inputs vals) of time_tk_str, offset and datelab
will be returned.
If an error is encountered, then -1 is returned
This function calls upon the "SECTIME", "SECDATE", "DATESEC",
"MONTHYRFROM" and "yrfrom" procedures.
REVISION HISTORY:
@(#)timetick.pro 1.6 31 Jul 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Dec. '91
Revised Jan. '92 to cover time durations up to 20 years
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/timetick.pro)
FUNCTION:
YRFROM
DESCRIPTION:
Function to build an array of strings of the format:
'YR-1-1'
given a start time in seconds since 1970.
The date in each string increases monotonically, in one year
increments for the number of strings requested, from the
start time given.
Input parameters are the time to start the strings in seconds
since 1970, Jan 1, 00:00, and the number of strings to output.
USAGE (SAMPLE CODE FRAGMENT):
; set an array of strings to month and year date representions
date_strings = yrfrom(16156800.0,8) ; 8 dates starting at
; 7 Jul 1970 0:0:0.00
; output result
PRINT, date_strings
--- Sample output would be
70-1-1 71-1-1 72-1-1 73-1-1 74-1-1 75-1-1 76-1-1 77-1-1
NOTES:
The start time in seconds is normally a float type, though
this isn't necessary.
If the input start time is negitive, this is an error, and the string
'ERROR' is returned.
If an array of start times is given, then a two dimensional array
of dimensions (n_dates,N_ELEMENTS(inputs vals)) of stings will
be returned.
This routine calls the function "SECDATE".
REVISION HISTORY:
@(#)yrfrom.pro 1.3 18 Aug 1995
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Feb. '92
(See /disks/aeolus/disk1/wind/source/idl/general/obsolete/idlUtil/yrfrom.pro)