Document handling different types and encodings
This commit is contained in:
parent
5114a3ea08
commit
736b4caeeb
32
README.md
32
README.md
|
@ -52,10 +52,8 @@ This example shows how to read and write tag fields in a format-independent way:
|
||||||
#include <tagparser/mediafileinfo.h>
|
#include <tagparser/mediafileinfo.h>
|
||||||
#include <tagparser/diagnostics.h>
|
#include <tagparser/diagnostics.h>
|
||||||
|
|
||||||
using namespace TagParser;
|
|
||||||
|
|
||||||
// create a MediaFileInfo for high-level access to overall functionality of the library
|
// create a MediaFileInfo for high-level access to overall functionality of the library
|
||||||
MediaFileInfo fileInfo;
|
TagParser::MediaFileInfo fileInfo;
|
||||||
// create container for errors, warnings, etc.
|
// create container for errors, warnings, etc.
|
||||||
Diagnostics diag;
|
Diagnostics diag;
|
||||||
|
|
||||||
|
@ -63,45 +61,47 @@ Diagnostics diag;
|
||||||
fileInfo.setPath("/path/to/some/file");
|
fileInfo.setPath("/path/to/some/file");
|
||||||
fileInfo.open();
|
fileInfo.open();
|
||||||
// parse tags
|
// 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);
|
fileInfo.parseTags(diag);
|
||||||
|
|
||||||
// get first tag as an object derived from the Tag class
|
// get first tag as an object derived from the Tag class
|
||||||
auto tag = fileInfo.tags().at(0);
|
auto tag = fileInfo.tags().at(0);
|
||||||
// extract title and convert it to UTF-8 std::string
|
// extract title and convert it to UTF-8 std::string
|
||||||
// (toString() might throw ConversionException)
|
// (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
|
// 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
|
// 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
|
// 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);
|
fileInfo.applyChanges(diag, progress);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Summary
|
### Summary
|
||||||
|
* The most important class is `TagParser::MediaFileInfo` providing access to everything else.
|
||||||
* So the most important class is `MediaFileInfo` providing access to everything else.
|
|
||||||
* IO errors are propagated via standard `std::ios_base::failure`.
|
* IO errors are propagated via standard `std::ios_base::failure`.
|
||||||
* Fatal processing errors are propagated by throwing a class derived from Failure.
|
* Fatal processing errors are propagated by throwing a class derived from `TagParser::Failure`.
|
||||||
* All operations which might generate warnings, non-fatal errors, ... take a `Diagnostics` object to store
|
* All operations which might generate warnings, non-fatal errors, ... take a `TagParser::Diagnostics` object to store
|
||||||
those messages.
|
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.
|
for callbacks and aborting.
|
||||||
* Field values are stored using `TagValue` objects. Those objects erase the actual type similar to `QVariant`
|
* Field values are stored using `TagParser::TagValue` objects. Those objects erase the actual type similar to `QVariant`
|
||||||
from the Qt framework.
|
from the Qt framework. The documentation of `TagParser::TagValue` covers how different types and encodings are
|
||||||
|
handled.
|
||||||
|
|
||||||
### Further documentation
|
### Further documentation
|
||||||
For more examples check out the command line interface of [Tag Editor](https://github.com/Martchus/tageditor).
|
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`.
|
API documentation can be generated using Doxygen with `make tagparser_apidoc`.
|
||||||
|
|
||||||
## Bugs, stability
|
## Bugs, stability
|
||||||
|
Bugs can be reported on GitHub.
|
||||||
|
|
||||||
It is recommend to create backups before editing because I can not test whether the library
|
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
|
## Build instructions
|
||||||
The tagparser library depends on [c++utilities](https://github.com/Martchus/cpp-utilities) and is built
|
The tagparser library depends on [c++utilities](https://github.com/Martchus/cpp-utilities) and is built
|
||||||
|
|
17
tagvalue.cpp
17
tagvalue.cpp
|
@ -69,6 +69,23 @@ pair<const char *, float> encodingParameter(TagTextEncoding tagTextEncoding)
|
||||||
* \brief The TagValue class wraps values of different types. It is meant to be assigned to a tag field.
|
* \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.
|
* 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.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/*!
|
/*!
|
||||||
|
|
Loading…
Reference in New Issue