.\" * jstrftime.3 - Tools for manipulating Jalali representation of Iranian calendar
.\" * and necessary conversations to Gregorian calendar.
.\" * Copyright (C) 2006, 2007, 2009, 2010, 2011 Ashkan Ghassemi.
.\" *
.\" * This file is part of libjalali.
.\" *
.\" * libjalali is free software: you can redistribute it and/or modify
.\" * it under the terms of the GNU Lesser General Public License as published by
.\" * the Free Software Foundation, either version 3 of the License, or
.\" * (at your option) any later version.
.\" *
.\" * libjalali is distributed in the hope that it will be useful,
.\" * but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" * GNU Lesser General Public License for more details.
.\" *
.\" * You should have received a copy of the GNU Lesser General Public License
.\" * along with libjalali.  If not, see <http://www.gnu.org/licenses/>.

.TH JSTRPTIME 3 2011-05-28 "GNU" "libjalali Manual"
.SH NAME
jstrptime \- convert a string representation of jalali date and time to a jalali time jtm structure
.SH SYNOPSIS
.B #include <time.h>
.sp
.BI "char *jstrptime(const char *" s ", const char *" format ,
.BI "struct jtm *" jtm );
.sp
Link with -ljalali
.SH DESCRIPTION
The
.BR jstrptime ()
function is the converse function to
.BR jstrftime (3)
and converts the character string pointed to by
.I s
to values which are stored in the
.I jtm
structure pointed to by
.IR jtm ,
using the format specified by
.IR format .
Here
.I format
is a character string that consists of field descriptors and text characters,
reminiscent of
.BR scanf (3).
Each field descriptor consists of a
.B %
character followed by another character that specifies the replacement
for the field descriptor.
All other characters in the
.I format
string must have a matching character in the input string.
There should be white\%space or other alphanumeric characters
between any two field descriptors.
.PP
The
.BR jstrptime ()
function processes the input string from left
to right.
Each of the three possible input elements (whitespace,
literal, or format) are handled one after the other.
If the input cannot be matched to the format string the function stops.
The remainder of the format and input strings are not processed.
.PP
The supported input field descriptors are listed below.
In case a text string (such as a weekday or month name)
is to be matched, the comparison is case insensitive.
In case a number is to be matched, leading zeros are
permitted but not required.
.TP
.B %%
The
.B %
character.
.TP
.BR %a " or " %A " or " %h " or " %q
The weekday name in abbreviated form or the full name.
.TP
.BR %b " or " %B
The month name in abbreviated form or the full name.
.TP
.BR %d " or " %e
The day of month (1-31).
.TP
.B %H
The hour (0-23).
.TP
.B %j
The day number in the year (1-366).
.TP
.B %m
The month number (1-12).
.TP
.B %M
The minute (0-59).
.TP
.B %s
Seconds since UTC Epoch.
.TP
.B %S
The second (0-59).
.TP
.B %y
The year within century (0-99).
When a century is not otherwise specified, values in the range 19-99 refer
to years in the fourteenth century (1319-1399); values in the
range 00-18 refer to years in the fifteenth century (1400-1418).
.TP
.B %Y
The year, including century (for example, 1390).
.LP
The broken-down jalali time structure \fIjtm\fP is defined in \fI<jtime.h>\fP
as follows:
.sp
.in +4n
.nf
struct jtm {
    int tm_sec;        /* seconds */
    int tm_min;        /* minutes */
    int tm_hour;       /* hours */
    int tm_mday;       /* day of the month */
    int tm_mon;        /* month */
    int tm_year;       /* year */
    int tm_wday;       /* day of the week */
    int tm_yday;       /* day in the year */
    int tm_isdst;      /* daylight saving time */
};
.fi
.in
.SH "RETURN VALUE"
The return value of the function is a pointer to the first character
not processed in this function call.
In case the input string
contains more characters than required by the format string the return
value points right after the last consumed input character.
In case
the whole input string is consumed the return value points to the null
byte at the end of the string.
If
.BR jstrptime ()
fails to match all
of the format string and therefore an error occurred the function
returns NULL.
.SH "CONFORMING TO"
C99.
.SH NOTES
.LP
In principle, this function does not initialize \fIjtm\fP but
only stores the values specified.
This means that \fIjtm\fP should be initialized before the call.
libjalali does not touch those fields which are not
explicitly specified.

.SH EXAMPLE
The following example demonstrates the use of
.BR jstrptime (3)
and
.BR jstrftime (3).
.sp
.nf
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <jalali.h>
#include <jtime.h>

int
main(void)
{
    struct jtm tm;
    char buf[255];

    memset(&jtm, 0, sizeof(struct jtm));
    jstrptime("1390\-03\-17 08:33:01", "%Y\-%m\-%d %H:%M:%S", &jtm);
    jstrftime(buf, sizeof(buf), "%d %b %Y %H:%M", &jtm);
    puts(buf);
    exit(EXIT_SUCCESS);
}
.fi
.SH "SEE ALSO"
.BR time (2),
.BR jdate (1),
.BR jcal (1),
.BR getdate (3),
.BR scanf (3),
.BR jstrftime (3),
.BR jctime (3),
.BR feature_test_macros (7)
.SH COLOPHON
This page is part of release 0.2 of the libjalali
.I man-pages
.SH AUTHOR
Written by Ashkan Ghassemi. <ghassemi@ftml.net>
.SH REPORTING BUGS
Report libjalali bugs to <ghassemi@ftml.net>

libjalali home page: <http://savannah.nongnu.org/projects/jcal/>
.SH COPYRIGHT
Copyright (C) 2011 Ashkan Ghassemi.

License LGPLv3+: GNU LGPL version 3 or later
<http://gnu.org/licenses/lgpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by
law.