From 736b4caeeb7d4d483a03ff800d14777252e3e91f Mon Sep 17 00:00:00 2001 From: Martchus Date: Sat, 1 Jun 2019 23:20:01 +0200 Subject: [PATCH] Document handling different types and encodings --- README.md | 32 ++++++++++++++++---------------- tagvalue.cpp | 17 +++++++++++++++++ 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a2c5aff..44d55a2 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,8 @@ This example shows how to read and write tag fields in a format-independent way: #include #include -using namespace TagParser; - // create a MediaFileInfo for high-level access to overall functionality of the library -MediaFileInfo fileInfo; +TagParser::MediaFileInfo fileInfo; // create container for errors, warnings, etc. Diagnostics diag; @@ -63,45 +61,47 @@ Diagnostics diag; fileInfo.setPath("/path/to/some/file"); fileInfo.open(); // parse tags -// (might throw exception derived from Failure for fatal parsing error or ios_base::failure for IO errors) +// (might throw exception derived from TagParser::Failure for fatal parsing error or ios_base::failure for IO errors) fileInfo.parseTags(diag); // get first tag as an object derived from the Tag class auto tag = fileInfo.tags().at(0); // extract title and convert it to UTF-8 std::string // (toString() might throw ConversionException) -auto title = tag->value(KnownField::Title).toString(TagTextEncoding::Utf8); +auto title = tag->value(TagParser::KnownField::Title).toString(TagParser::TagTextEncoding::Utf8); // change album using an encoding suitable for the tag format -tag->setValue(KnownField::Album, TagValue("some UTF-8 string", TagTextEncoding::Utf8, tag->proposedTextEncoding())); +tag->setValue(TagParser::KnownField::Album, TagParser::TagValue("some UTF-8 string", TagParser::TagTextEncoding::Utf8, tag->proposedTextEncoding())); // create progress -AbortableProgressFeedback progress([callback for status update], [callback for percentage-only updates]); +TagParser::AbortableProgressFeedback progress([callback for status update], [callback for percentage-only updates]); // apply changes to the file on disk -// (might throw exception derived from Failure for fatal processing error or ios_base::failure for IO errors) +// (might throw exception derived from TagParser::Failure for fatal processing error or ios_base::failure for IO errors) fileInfo.applyChanges(diag, progress); ``` ### Summary - -* So the most important class is `MediaFileInfo` providing access to everything else. +* The most important class is `TagParser::MediaFileInfo` providing access to everything else. * IO errors are propagated via standard `std::ios_base::failure`. -* Fatal processing errors are propagated by throwing a class derived from Failure. -* All operations which might generate warnings, non-fatal errors, ... take a `Diagnostics` object to store +* Fatal processing errors are propagated by throwing a class derived from `TagParser::Failure`. +* All operations which might generate warnings, non-fatal errors, ... take a `TagParser::Diagnostics` object to store those messages. -* All operations which can be aborted or provide progress feedback take a `AbortableProgressFeedback` object +* All operations which can be aborted or provide progress feedback take a `TagParser::AbortableProgressFeedback` object for callbacks and aborting. -* Field values are stored using `TagValue` objects. Those objects erase the actual type similar to `QVariant` - from the Qt framework. +* Field values are stored using `TagParser::TagValue` objects. Those objects erase the actual type similar to `QVariant` + from the Qt framework. The documentation of `TagParser::TagValue` covers how different types and encodings are + handled. ### Further documentation For more examples check out the command line interface of [Tag Editor](https://github.com/Martchus/tageditor). API documentation can be generated using Doxygen with `make tagparser_apidoc`. ## Bugs, stability +Bugs can be reported on GitHub. + It is recommend to create backups before editing because I can not test whether the library -works with all kinds of files (when forcing rewrite a backup is always created). +works with all kinds of files. (When forcing rewrite a backup is always created.) ## Build instructions The tagparser library depends on [c++utilities](https://github.com/Martchus/cpp-utilities) and is built diff --git a/tagvalue.cpp b/tagvalue.cpp index 258092d..5942ee0 100644 --- a/tagvalue.cpp +++ b/tagvalue.cpp @@ -69,6 +69,23 @@ pair encodingParameter(TagTextEncoding tagTextEncoding) * \brief The TagValue class wraps values of different types. It is meant to be assigned to a tag field. * * For a list of supported types see TagParser::TagDataType. + * + * When constructing a TagValue choose the type which suites the value you want to store best. If the + * tag format uses a different type the serializer will take care of the neccassary conversion (eg. convert + * an integer to a string). + * + * When consuming a TagValue read from a tag one should not expect that a particular type is used. The + * type depends on what the particular tag format uses. However, the conversion functions provided by the + * TagValue class take care of neccassary conversions, eg. TagValue::toInteger() will attempt to convert a + * string to a number (an possibly throw a ConversionException on failure). + * + * Values of the type TagDataType::Text can be differently encoded. See TagParser::TagTextEncoding for a + * list of supported encodings. Be sure to use an encoding which is supported by the tag implementation. + * To ensure that the functions Tag::canEncodingBeUsed(), Tag::proposedTextEncoding() and + * Tag::ensureTextValuesAreProperlyEncoded() can be used. + * + * Values of the type TagDataType::Text are not supposed to contain Byte-Order-Marks. Before assigning text + * which might be prepended by a Byte-Order-Mark the helper function TagValue::stripBom() can be used. */ /*!