File indexing completed on 2024-10-06 12:27:19

 /*
     This file is part of the syndication library
     SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef SYNDICATION_TOOLS_H
 #define SYNDICATION_TOOLS_H
 
 #include "syndication_export.h"
 #include <syndication/person.h>
 
 #include <QString>
 
 class QByteArray;
 class QString;
 
 namespace Syndication
 {
 /** date formats supported by date parsers */
 
 enum DateFormat {
     ISODate, /**< ISO 8601 extended format.
               * (date: "2003-12-13",datetime: "2003-12-13T18:30:02.25",
               * datetime with timezone: "2003-12-13T18:30:02.25+01:00")
               */
     RFCDate, /**< RFC 822. (e.g. "Sat, 07 Sep 2002 00:00:01 GMT") */
 };
 
 /**
  * parses a date string in ISO 8601 extended format.
  * (date: "2003-12-13",datetime: "2003-12-13T18:30:02.25",
  * datetime with timezone: "2003-12-13T18:30:02.25+01:00")
  *
  * @param str a string in ISO 8601 format
  * @return parsed date in seconds since epoch, 0 if no date could
  * be parsed from the string.
  */
 SYNDICATION_EXPORT
 uint parseISODate(const QString &str);
 
 /**
  * parses a date string as defined in RFC 822.
  * (Sat, 07 Sep 2002 00:00:01 GMT)
  *
  * @param str a string in RFC 822 format
  * @return parsed date in seconds since epoch, 0 if no date could
  * be parsed from the string.
  */
 SYNDICATION_EXPORT
 uint parseRFCDate(const QString &str);
 
 /**
  * parses a date string in ISO (see parseISODate()) or RFC 822 (see
  * parseRFCDate()) format.
  * It tries both parsers and returns the first valid parsing result found (or 0
  * otherwise).
  * To speed up parsing, you can give a hint which format you expect.
  * The method will try the corresponding parser first then.
  *
  * @param str a date string
  * @param hint the expected format
  * @return parsed date in seconds since epoch, 0 if no date could
  * be parsed from the string.
  */
 SYNDICATION_EXPORT
 uint parseDate(const QString &str, DateFormat hint = RFCDate);
 
 /**
  * @internal
  * returns a string representation of a datetime.
  * this is used internally to create debugging output.
  *
  * @param date the date to convert
  * @return string representation of the date, or a null string if
  * @c date is 0
  */
 SYNDICATION_EXPORT
 QString dateTimeToString(uint date);
 
 /**
  * resolves entities to respective unicode chars.
  *
  * @param str a string
  */
 SYNDICATION_EXPORT
 QString resolveEntities(const QString &str);
 /**
  * replaces the characters &lt; >, &, ", '
  * with &amp;lt; &amp;gt; &amp;amp;, &amp;quot; &amp;apos;.
  * @param str the string to escape
  */
 SYNDICATION_EXPORT
 QString escapeSpecialCharacters(const QString &str);
 
 /**
  * replaces newlines ("\n") by &lt;br/>
  * @param str string to convert
  */
 SYNDICATION_EXPORT
 QString convertNewlines(const QString &str);
 
 /**
  * converts a plain text string to HTML
  *
  * @param plainText a string in plain text.
  */
 SYNDICATION_EXPORT
 QString plainTextToHtml(const QString &plainText);
 
 /**
  * converts a HTML string to plain text
  *
  * @param html string in HTML format
  * @return stripped text
  */
 SYNDICATION_EXPORT
 QString htmlToPlainText(const QString &html);
 
 /**
  * guesses whether a string contains plain text or HTML
  *
  * @param str the string in unknown format
  * @return @c true if the heuristic thinks it's HTML, @c false
  * if thinks it is plain text
  */
 SYNDICATION_EXPORT
 bool isHtml(const QString &str);
 
 /**
  * guesses whether a string contains (HTML) markup or not. This
  * implements not an exact check for valid HTML markup, but a
  * simple (and relatively fast) heuristic.
  *
  * @param str the string that might or might not contain markup
  * @return @c true if the heuristic thinks it contains markup, @c false
  * if thinks it is markup-free plain text
  */
 SYNDICATION_EXPORT
 bool stringContainsMarkup(const QString &str);
 
 /**
  * Ensures HTML formatting for a string.
  * guesses via isHtml() if @c str contains HTML or plain text, and returns
  * plainTextToHtml(str) if it thinks it is plain text, or the unmodified @c str
  * otherwise.
  *
  * @param str a string with unknown content
  * @return string as HTML (as long as the heuristics work)
  */
 SYNDICATION_EXPORT
 QString normalize(const QString &str);
 
 /**
  * normalizes a string based on feed-wide properties of tag content.
  * It is based on the assumption that all items in a feed encode their
  * title/description content in the same way (CDATA or not, plain text
  * vs. HTML). isCDATA and containsMarkup are determined once by the feed,
  * and then passed to this method.
  *
  * The returned string contains HTML, with special characters &lt;, >,
  * &, ", and ' escaped, and all other entities resolved.
  * Whitespace is collapsed, relevant whitespace is replaced by respective
  * HTML tags (&lt;br/>).
  *
  * @param str a string
  * @param isCDATA whether the feed uses CDATA for the tag @c str was read from
  * @param containsMarkup whether the feed uses HTML markup in the
  *        tag @c str was read from.
  * @return string as HTML (as long as the heuristics work)
  */
 SYNDICATION_EXPORT
 QString normalize(const QString &str, bool isCDATA, bool containsMarkup);
 
 /**
  * Parses a person object from a string by identifying name and email address
  * in the string. Currently detected variants are:
  * "foo@bar.com", "Foo", "Foo &lt;foo@bar.com>", "foo@bar.com (Foo)".
  *
  * @param str the string to parse the person from.
  * @return a Person object containing the parsed information.
  */
 SYNDICATION_EXPORT
 PersonPtr personFromString(const QString &str);
 
 /**
  * @internal
  * calculates a hash value for a string
  */
 unsigned int calcHash(const QString &str);
 
 /**
  * @internal
  * calculates a hash value for a byte array
  */
 unsigned int calcHash(const QByteArray &array);
 
 /**
  * @internal
  * calculates a md5 checksum for a string
  */
 QString calcMD5Sum(const QString &str);
 
 //@cond PRIVATE
 /**
  * @internal
  * used internally to represent element types
  */
 struct ElementType {
     ElementType(const QString &localnamep,
                 const QString &nsp = QString()); // implicit
 
     bool operator==(const ElementType &other) const;
 
     QString ns;
     QString localname;
 };
 //@endcond
 
 } // namespace Syndication
 
 #endif // SYNDICATION_TOOLS_H