Mail::Message::Field::Date(3)              User Contributed Perl Documentation


NAME
       Mail::Message::Field::Date - message header field with uris

INHERITANCE
        Mail::Message::Field::Date
          is a Mail::Message::Field::Structured
          is a Mail::Message::Field::Full
          is a Mail::Message::Field
          is a Mail::Reporter

SYNOPSIS
         my $f = Mail::Message::Field->new(Date => time);
         my $f = Mail::Message::Field::Date->new(Date => time);
         my $date = $f->date;    # cleaned-up and validated
         my $time = $date->time; # converted to POSIX time

DESCRIPTION
       Dates are a little more tricky than it should be: the formatting
       permits a few constructs more than other RFCs use for timestamps.  For
       instance, a small subset of timezone abbreviations are permitted.

       The studied date field will reformat the content into a standard form.

       Extends "DESCRIPTION" in Mail::Message::Field::Structured.

OVERLOADED
       Extends "OVERLOADED" in Mail::Message::Field::Structured.

       overload: "" stringification
           Inherited, see "OVERLOADED" in Mail::Message::Field::Full

       overload: '""' stringification
           Inherited, see "OVERLOADED" in Mail::Message::Field

       overload: '0+' numification
           Inherited, see "OVERLOADED" in Mail::Message::Field

       overload: '<='> numeric comparison
           Inherited, see "OVERLOADED" in Mail::Message::Field

       overload: bool boolean
           Inherited, see "OVERLOADED" in Mail::Message::Field

       overload: cmp string comparison
           Inherited, see "OVERLOADED" in Mail::Message::Field

METHODS
       Extends "METHODS" in Mail::Message::Field::Structured.

   Constructors
       Extends "Constructors" in Mail::Message::Field::Structured.

       $obj->clone()
           Inherited, see "Constructors" in Mail::Message::Field

       $class->from($field, %options)
           Inherited, see "Constructors" in Mail::Message::Field::Full

       $class->new($data)
           Inherited, see "METHODS" in Mail::Message::Field::Structured

            -Option    --Defined in                      --Default
             attributes  Mail::Message::Field::Structured  <ignored>
             charset     Mail::Message::Field::Full        undef
             datum       Mail::Message::Field::Structured  undef
             encoding    Mail::Message::Field::Full        'q'
             force       Mail::Message::Field::Full        false
             language    Mail::Message::Field::Full        undef

           attributes => \@attributes|\%attributes
           charset => $charset
           datum => $date
           encoding => 'q'|'Q'|'b'|'B'
           force => BOOLEAN
           language => $language

           >> example:

             my $mmfd = 'Mail::Message::Field::Date';
             my $f = $mmfd->new(Date => time);

   Attributes
       Extends "Attributes" in Mail::Message::Field::Structured.

       $obj->Name()
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->body()
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->folded()
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->foldedBody( [$body] )
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->name()
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->unfoldedBody( [$body, [$wrap]] )
           Inherited, see "Attributes" in Mail::Message::Field

       $obj->wellformedName( [STRING] )
           Inherited, see "Attributes" in Mail::Message::Field

   The field
       Extends "The field" in Mail::Message::Field::Structured.

       $any->isStructured( [$name] )
           Inherited, see "The field" in Mail::Message::Field

       $obj->length()
           Inherited, see "The field" in Mail::Message::Field

       $obj->nrLines()
           Inherited, see "The field" in Mail::Message::Field

       $obj->print( [$fh] )
           Inherited, see "The field" in Mail::Message::Field

       $obj->size()
           Inherited, see "The field" in Mail::Message::Field

       $obj->string( [$wrap] )
           Inherited, see "The field" in Mail::Message::Field

       $obj->toDisclose()
           Inherited, see "The field" in Mail::Message::Field

   Access to the body
       Extends "Access to the body" in Mail::Message::Field::Structured.

       $obj->decodedBody(%options)
           Inherited, see "Access to the body" in Mail::Message::Field::Full

   Access to the content
       Extends "Access to the content" in Mail::Message::Field::Structured.

       $obj->addAttribute(...)
           Attributes are not supported for date fields.

       $obj->addresses()
           Inherited, see "Access to the content" in Mail::Message::Field

       $obj->attrPairs()
           Inherited, see "Access to the content" in
           Mail::Message::Field::Structured

       $obj->attribute( $object|<STRING, %options>|<$name,$value,%options> )
           Inherited, see "Access to the content" in
           Mail::Message::Field::Structured

       $obj->attributes()
           Inherited, see "Access to the content" in
           Mail::Message::Field::Structured

       $obj->beautify()
           Inherited, see "Access to the content" in
           Mail::Message::Field::Full

       $obj->comment( [STRING] )
           Inherited, see "Access to the content" in Mail::Message::Field

       $any->createComment(STRING, %options)
           Inherited, see "Access to the content" in
           Mail::Message::Field::Full

       $any->createPhrase(STRING, %options)
           Inherited, see "Access to the content" in
           Mail::Message::Field::Full

       $obj->date()
           The validated and standardized date representation for this field.
           When the body of this field is not recognized, then this will
           return "undef".

       $any->dateToTimestamp(STRING)
           Inherited, see "Access to the content" in Mail::Message::Field

       $any->stripCFWS( [STRING] )
           Inherited, see "Access to the content" in Mail::Message::Field

       $obj->study()
           Inherited, see "Access to the content" in Mail::Message::Field

       $obj->time()
           Convert date into a timestamp, as produced with POSIX::time().

       $any->toDate( [$time] )
           Inherited, see "Access to the content" in Mail::Message::Field

       $obj->toInt()
           Inherited, see "Access to the content" in Mail::Message::Field

   Internals
       Extends "Internals" in Mail::Message::Field::Structured.

       $any->decode(STRING, %options)
           Inherited, see "Internals" in Mail::Message::Field::Full

       $obj->encode(STRING, %options)
           Inherited, see "Internals" in Mail::Message::Field::Full

   Parsing
       Extends "Parsing" in Mail::Message::Field::Structured.

       $obj->consume( $line | <$name,<$body|$objects>> )
           Inherited, see "Parsing" in Mail::Message::Field

       $any->consumeComment(STRING)
           Inherited, see "Parsing" in Mail::Message::Field::Full

       $obj->consumeDotAtom(STRING)
           Inherited, see "Parsing" in Mail::Message::Field::Full

       $any->consumePhrase(STRING)
           Inherited, see "Parsing" in Mail::Message::Field::Full

       $obj->datum( [$value] )
           Inherited, see "Parsing" in Mail::Message::Field::Structured

       $obj->defaultWrapLength( [$length] )
           Inherited, see "Parsing" in Mail::Message::Field

       $any->fold( $name, $body, [$maxchars] )
           Inherited, see "Parsing" in Mail::Message::Field

       $obj->parse(STRING)
           Inherited, see "Parsing" in Mail::Message::Field::Full

       $obj->produceBody()
           Inherited, see "Parsing" in Mail::Message::Field::Full

       $obj->setWrapLength( [$length] )
           Inherited, see "Parsing" in Mail::Message::Field

       $obj->stringifyData(STRING|ARRAY|$objects)
           Inherited, see "Parsing" in Mail::Message::Field

       $obj->unfold(STRING)
           Inherited, see "Parsing" in Mail::Message::Field

   Error handling
       Extends "Error handling" in Mail::Message::Field::Structured.

       $obj->AUTOLOAD()
           Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
           Inherited, see "Error handling" in Mail::Reporter

   Cleanup
       Extends "Cleanup" in Mail::Message::Field::Structured.

       $obj->DESTROY()
           Inherited, see "Cleanup" in Mail::Reporter

DETAILS
       Extends "DETAILS" in Mail::Message::Field::Structured.

DIAGNOSTICS
       Error: class $package does not implement method $method.
           Fatal error: the specific $package (or one of its superclasses)
           does not implement this method where it should. This message means
           that some other related classes do implement this method however
           the class at hand does not.  Probably you should investigate this
           and probably inform the author of the package.  Cast by
           notImplemented()

       Warning: field content is not numerical: $content
           The numeric value of a field is requested (for instance the "Lines"
           or "Content-Length" fields should be numerical), however the data
           contains weird characters.  Cast by toInt()

       Error: field name too long (max $count), in '$name'.
           It is not specified in the RFCs how long a field name can be, but
           at least it should be a few characters shorter than the line wrap.
           Cast by fold()

       Warning: illegal character in charset '$name'.
           The field is created with an utf8 string which only contains data
           from the specified character set.  However, that character set can
           never be a valid name because it contains characters which are not
           permitted.  Cast by encode()

       Warning: illegal character in field name $name.
           A new field is being created which does contain characters not
           permitted by the RFCs.  Using this field in messages may break
           other e-mail clients or transfer agents, and therefore mutulate or
           extinguish your message.  Cast by consume()

       Warning: illegal character in language '$name'.
           The field is created with data which is specified to be in a
           certain language, however, the name of the language cannot be
           valid: it contains characters which are not permitted by the RFCs.
           Cast by encode()

       Warning: illegal encoding '$name', using 'q'.
           The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
           or "Q") encoding.  Other than these four options are illegal.  Cast
           by encode()

       Error: no attributes for date fields.
           It is not possible to add attributes to date fields: it is not
           permitted by the RFCs.  Cast by addAttribute()

SEE ALSO
       This module is part of Mail-Message version 4.05, built on April 10,
       2026. Website: http://perl.overmeer.net/mailbox/

LICENSE
       For contributors see file ChangeLog.

       This software is copyright (c) 2001-2026 by Mark Overmeer.

       This is free software; you can redistribute it and/or modify it under
       the same terms as the Perl 5 programming language system itself.

perl v5.42.2                      2026-04-11     Mail::Message::Field::Date(3)