diff mbox

[libfortran] PR 47802 Update documentation for CTIME and FDATE

Message ID AANLkTi=9TW30+FqttryXsLJOaCMB+PC4j9dRP-iW_gtC@mail.gmail.com
State New
Headers show

Commit Message

Janne Blomqvist March 1, 2011, 9:26 p.m. UTC 
Hi,

as the recent patches to make CTIME and FDATE thread-safe also
modified the behavior in that those intrinsics now create a localized
string if the application has called setlocale(), attached is a patch
that updates the documentation to match.

Ok for trunk?

2011-03-01  Janne Blomqvist  <jb@gcc.gnu.org>

	PR libfortran/47802
	* gcc/fortran/intrinsics.texi: Update CTIME and FDATE
	documentation.

Comments

Tobias Burnus March 4, 2011, 1:56 p.m. UTC | #1 
On 03/01/2011 10:26 PM, Janne Blomqvist wrote:
> Ok for trunk?

  @code{CTIME} converts a system time value, such as returned by
-@code{TIME8}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
+@code{TIME8}, to a localized string. Unless the application has called
+@code{setlocale}, the output will be in the default locale, of length
+24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
+a longer string may result.


I would suggest to remove the first "localized" - it gives too much 
focus on the localization, which is usually not happening. (Side remark: 
As it is a kind=1 string, certain localizations are not really possible 
or in UTF-8 cause string-length issues.)

You should mention that - in case of the subroutine version - the RESULT 
will be blank if the string does not fit.

+default kind. It is an @code{INTENT(OUT)} argument.  If the length of
+this variable is too short for the localized date and time string to
+fit completely, it will be empty on procedure return.


I think you should scratch the "localized" here and use the wording from 
ctime. Additionally, "empty" is not really a concept of a string. I 
think you should use the word "blank". (The word "empty" fits  better 
for the result variable which would be is a string of length 0.)

(The repetition of the ctime wording might sound superfluous, but most 
readers directly jump to the function, not knowing the ctime wording 
when looking for ftime.)

  @item @emph{Return value}:
-The current date as a string.
+The current date and time as a localized string.  If the
+@code{CHARACTER} variable to which the result is assigned is too
+short, the result is truncated.


Again, I would leave out the "localized" here - and only mention it 
together with setlocale in the Description. I am also not sure one needs 
the words about truncation as this is a general concept of string 
assignment. (Additionally, it is not quite true: Instead of truncation 
also a reallocation with the right size could happen - for allocatable 
"len=:" strings.)

With the nits fixed - or at least considered, the patch is OK. Thanks 
for working on thread safety.

Tobias
> 2011-03-01  Janne Blomqvist<jb@gcc.gnu.org>
>
> 	PR libfortran/47802
> 	* gcc/fortran/intrinsics.texi: Update CTIME and FDATE
> 	documentation.
>
>
diff mbox

Patch

diff --git a/gcc/fortran/intrinsic.texi b/gcc/fortran/intrinsic.texi
index 1ff4db3..f1ac6d2 100644
--- a/gcc/fortran/intrinsic.texi
+++ b/gcc/fortran/intrinsic.texi
@@ -3218,7 +3218,10 @@  end program test_cshift
 @table @asis
 @item @emph{Description}:
 @code{CTIME} converts a system time value, such as returned by
-@code{TIME8}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
+@code{TIME8}, to a localized string. Unless the application has called
+@code{setlocale}, the output will be in the default locale, of length
+24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
+a longer string may result.
 
 This intrinsic is provided in both subroutine and function forms; however,
 only one form can be used in any given program unit.
@@ -3232,18 +3235,22 @@  Subroutine, function
 @item @emph{Syntax}:
 @multitable @columnfractions .80
 @item @code{CALL CTIME(TIME, RESULT)}.
-@item @code{RESULT = CTIME(TIME)}, (not recommended).
+@item @code{RESULT = CTIME(TIME)}.
 @end multitable
 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
-@item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
+@item @var{TIME}    @tab The type shall be of type @code{INTEGER}.
 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
-of default kind.
+of default kind. It is an @code{INTENT(OUT)} argument. If the length
+of this variable is too short for the localized time and date string
+to fit completely, it will be empty on procedure return.
 @end multitable
 
 @item @emph{Return value}:
-The converted date and time as a string.
+The converted date and time as a string. If the @code{CHARACTER} to
+which the result is assigned is too short, the result is truncated.
+
 
 @item @emph{Example}:
 @smallexample
@@ -3260,7 +3267,7 @@  end program test_ctime
 @end smallexample
 
 @item @emph{See Also}:
-@ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
+@ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
 @end table
 
 
@@ -4420,9 +4427,6 @@  TIME())}.
 This intrinsic is provided in both subroutine and function forms; however,
 only one form can be used in any given program unit.
 
-@var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
-default kind.
-
 @item @emph{Standard}:
 GNU extension
 
@@ -4432,17 +4436,21 @@  Subroutine, function
 @item @emph{Syntax}:
 @multitable @columnfractions .80
 @item @code{CALL FDATE(DATE)}.
-@item @code{DATE = FDATE()}, (not recommended).
+@item @code{DATE = FDATE()}.
 @end multitable
 
 @item @emph{Arguments}:
 @multitable @columnfractions .15 .70
 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
-default kind
+default kind. It is an @code{INTENT(OUT)} argument.  If the length of
+this variable is too short for the localized date and time string to
+fit completely, it will be empty on procedure return.
 @end multitable
 
 @item @emph{Return value}:
-The current date as a string.
+The current date and time as a localized string.  If the
+@code{CHARACTER} variable to which the result is assigned is too
+short, the result is truncated.
 
 @item @emph{Example}:
 @smallexample
@@ -4458,8 +4466,10 @@  program test_fdate
     print *, 'Program ended on ', date
 end program test_fdate
 @end smallexample
-@end table
 
+@item @emph{See also}:
+@ref{DATE_AND_TIME}, @ref{CTIME}
+@end table
 
 
 @node FGET