globus_strptime.h

Go to the documentation of this file.
00001 /*
00002  * Copyright 1999-2006 University of Chicago
00003  * 
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  * 
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00022 #ifndef GLOBUS_STRPTIME_H
00023 #define GLOBUS_STRPTIME_H 1
00024  
00025 #include "globus_common_include.h"
00026  
00027  
00028 /******************************************************************************
00029 Function: globus_strptime()
00030 
00031 Description: 
00032 
00033   Parse and validate a date string (pointed to by parameter 1) based on a
00034   supplied format string (pointed to by parameter 2), putting the parsed and
00035   validated date values in a tm struct (pointed to by parameter 3).
00036   See description of the parameter "format_str" for a description of the
00037   parsing and validation rules.
00038 
00039 Parameters: 
00040 
00041   date_str:
00042     Points to the date string that is to be parsed and validated.
00043 
00044   format_str:
00045     Contains zero or more conversion specifications. (See description below.)
00046 
00047   time_ptr:
00048     A pointer to a struct tm  for returning the parsed and validated date data.
00049 
00050 Returns:
00051   pointer to character
00052     On successful completion:
00053         pointer to the first character of buffer that was not
00054         used in evaluating the format string.
00055     On unsuccessful completion:
00056         NULL pointer.
00057 
00058 
00059 Format specification:
00060     Each specification is composed of a '%' (percent) character followed by a
00061     conversion character specifying the required conversion.
00062     One or more white space characters may (optionally) precede or follow any
00063     conversion specification.
00064     Non-white space characters that are not part of a conversion specification
00065     may be included in the format string, and must be matched exactly
00066     (including case for letters) in the date_str. '%' (percent) can be
00067     specified as a character to match by using "%%".
00068     Multiple occurences of conversions for a given component of the date/time
00069     (second, minute, hour, day, day of month, month, year, century) is
00070     detected as an error.
00071     White space in the date_str will terminate a numeric value, but is
00072     otherwise skipped and ignored.
00073     All numeric fields are taken as decimal, must begin with a digit,
00074     and are matched up to a maximum number of digits (or the first
00075     non-digit).
00076     Note the the year returned in the tm_year field of the tm struct is
00077     relative to 1900 (e.g., 58 means year 1958, -8 means year 1892).
00078     Also, if the year is specified, but not the century, then values
00079     50-99 are taken as 20th century, 00-49 are taken as 21st century.
00080 
00081     The following conversion specifications are recognized:
00082       %a %A         day of week  (3 character abbreviation or full name)
00083                     Validated as Sun-Sat, not validated as correct for
00084                     any specified date.
00085       %b %h %B      month name  (3 character abbreviation or full name)
00086       %C            century number  (Up to 2 digits)
00087       %d %e         day of month  (Up to 2 digits)
00088                     Validated as 1-31. If month is provided, further
00089                     validated as not 31 for February, April, June,
00090                     September, or November, nor 30 for February.
00091                     If year and month provided then validated as not 29
00092                     for February in a non-leap year.
00093       %D            date as %m/%d/%y
00094       %H            hour (0-23)  (Up to 2 digits)
00095                     Error if %p is used.
00096       %I            hour (1-12)  (Up to 2 digits)
00097                     Converted to 24 hour clock when put in struct tm.
00098                     Assumed AM unless %p flag is used.
00099       %m            month (1-12)  (Up to 2 digits)
00100                     Returned in the tm struct as (0-11).
00101       %M            minute (0-59)  (Up to 2 digits)
00102       %n            white space  (White space is ignored.)
00103       %p            AM or PM or A.M. or P.M. (case independent)
00104                     (Error if %I is used.)
00105       %R            %H:%M
00106       %S            seconds (0-61) allows for 1 or 2 leap seconds
00107                     (Up to 2 digits)
00108       %t            white space  (White space is ignored.)
00109       %T            %H:%M:%S
00110       %y            year within century  (Up to 2 digits)
00111       %Y            year with century  (Up to 4 digits)
00112   
00113     Any whitespace in format is ignored.
00114     Any whitespace in buffer serves to delimit numeric fields
00115         (such as second, minute, hour, day, month, year) but
00116         is otherwise ignored.
00117         (I.e., a run of spaces, tabs, etc. is matched by any
00118          run of spaces, tabs, etc. even if the corresponding
00119          characters are are not identical or the counts
00120          are not the same.)
00121     Characters that are not whitespace and are not preceded by '%'
00122         must match exactly.
00123     Allows %% as literal '%' in buffer.
00124     The buffer is matched to the end of the format and no further.
00125   
00126 
00127 ******************************************************************************/
00128 
00129 #ifdef __cplusplus
00130 extern "C" {
00131 #endif
00132 
00133 char*
00134 globus_strptime(
00135     char*       date_str,
00136     char*       format_str,
00137     struct tm*  time_ptr );
00138 
00139  
00140 #ifdef __cplusplus
00141 }
00142 #endif
00143 
00144 #endif /* GLOBUS_STRPTIME_H */

Generated on 17 Mar 2017 for globus_common by  doxygen 1.4.7