1/***************************************************************************
2 copyright : (C) 2012 by Michael Helmling
3 email : helmling@mathematik.uni-kl.de
4 ***************************************************************************/
5
6/***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
10 * *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
19 * 02110-1301 USA *
20 * *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
25
26#ifndef TAGLIB_PROPERTYMAP_H_
27#define TAGLIB_PROPERTYMAP_H_
28
29#include "tmap.h"
30#include "tstringlist.h"
31
32namespace TagLib {
33
34 typedef Map<String,StringList> SimplePropertyMap;
35
36 //! A map for format-independent <key,valuelist> tag representations.
37
38 /*!
39 * This map implements a generic representation of textual audio metadata
40 * ("tags") realized as pairs of a case-insensitive key
41 * and a nonempty list of corresponding values, each value being an arbitrary
42 * unicode String.
43 *
44 * Note that most metadata formats pose additional conditions on the tag keys. The
45 * most popular ones (Vorbis, APE, ID3v2) should support all ASCII only words of
46 * length between 2 and 16.
47 *
48 * This class can contain any tags, but here is a list of "well-known" tags that
49 * you might want to use:
50 *
51 * Basic tags:
52 *
53 * - TITLE
54 * - ALBUM
55 * - ARTIST
56 * - ALBUMARTIST
57 * - SUBTITLE
58 * - TRACKNUMBER
59 * - DISCNUMBER
60 * - DATE
61 * - ORIGINALDATE
62 * - GENRE
63 * - COMMENT
64 *
65 * Sort names:
66 *
67 * - TITLESORT
68 * - ALBUMSORT
69 * - ARTISTSORT
70 * - ALBUMARTISTSORT
71 *
72 * Credits:
73 *
74 * - COMPOSER
75 * - LYRICIST
76 * - CONDUCTOR
77 * - REMIXER
78 * - PERFORMER:<XXXX>
79 *
80 * Other tags:
81 *
82 * - ISRC
83 * - ASIN
84 * - BPM
85 * - COPYRIGHT
86 * - ENCODEDBY
87 * - MOOD
88 * - COMMENT
89 * - MEDIA
90 * - LABEL
91 * - CATALOGNUMBER
92 * - BARCODE
93 *
94 * MusicBrainz identifiers:
95 *
96 * - MUSICBRAINZ_TRACKID
97 * - MUSICBRAINZ_ALBUMID
98 * - MUSICBRAINZ_RELEASEGROUPID
99 * - MUSICBRAINZ_WORKID
100 * - MUSICBRAINZ_ARTISTID
101 * - MUSICBRAINZ_ALBUMARTISTID
102 * - ACOUSTID_ID
103 * - ACOUSTID_FINGERPRINT
104 * - MUSICIP_PUID
105 *
106 */
107
108 class TAGLIB_EXPORT PropertyMap: public SimplePropertyMap
109 {
110 public:
111
112 typedef SimplePropertyMap::Iterator Iterator;
113 typedef SimplePropertyMap::ConstIterator ConstIterator;
114
115 PropertyMap();
116
117 PropertyMap(const PropertyMap &m);
118
119 /*!
120 * Creates a PropertyMap initialized from a SimplePropertyMap. Copies all
121 * entries from \a m that have valid keys.
122 * Invalid keys will be appended to the unsupportedData() list.
123 */
124 PropertyMap(const SimplePropertyMap &m);
125
126 virtual ~PropertyMap();
127
128 /*!
129 * Inserts \a values under \a key in the map. If \a key already exists,
130 * then \a values will be appended to the existing StringList.
131 * The returned value indicates success, i.e. whether \a key is a
132 * valid key.
133 */
134 bool insert(const String &key, const StringList &values);
135
136 /*!
137 * Replaces any existing values for \a key with the given \a values,
138 * and simply insert them if \a key did not exist before.
139 * The returned value indicates success, i.e. whether \a key is a
140 * valid key.
141 */
142 bool replace(const String &key, const StringList &values);
143
144 /*!
145 * Find the first occurrence of \a key.
146 */
147 Iterator find(const String &key);
148
149 /*!
150 * Find the first occurrence of \a key.
151 */
152 ConstIterator find(const String &key) const;
153
154 /*!
155 * Returns true if the map contains values for \a key.
156 */
157 bool contains(const String &key) const;
158
159 /*!
160 * Returns true if this map contains all keys of \a other
161 * and the values coincide for that keys. Does not take
162 * the unsupportedData list into account.
163 */
164 bool contains(const PropertyMap &other) const;
165
166 /*!
167 * Erase the \a key and its values from the map.
168 */
169 PropertyMap &erase(const String &key);
170
171 /*!
172 * Erases from this map all keys that appear in \a other.
173 */
174 PropertyMap &erase(const PropertyMap &other);
175
176 /*!
177 * Merge the contents of \a other into this PropertyMap.
178 * If a key is contained in both maps, the values of the second
179 * are appended to that of the first.
180 * The unsupportedData() lists are concatenated as well.
181 */
182 PropertyMap &merge(const PropertyMap &other);
183
184 /*!
185 * Returns a reference to the value associated with \a key.
186 *
187 * \note: If \a key is not contained in the map, an empty
188 * StringList is returned without error.
189 */
190 const StringList &operator[](const String &key) const;
191
192 /*!
193 * Returns a reference to the value associated with \a key.
194 *
195 * \note: If \a key is not contained in the map, an empty
196 * StringList is returned. You can also directly add entries
197 * by using this function as an lvalue.
198 */
199 StringList &operator[](const String &key);
200
201 /*!
202 * Returns true if and only if \other has the same contents as this map.
203 */
204 bool operator==(const PropertyMap &other) const;
205
206 /*!
207 * Returns false if and only \other has the same contents as this map.
208 */
209 bool operator!=(const PropertyMap &other) const;
210
211 /*!
212 * If a PropertyMap is read from a File object using File::properties(),
213 * the StringList returned from this function will represent metadata
214 * that could not be parsed into the PropertyMap representation. This could
215 * be e.g. binary data, unknown ID3 frames, etc.
216 * You can remove items from the returned list, which tells TagLib to remove
217 * those unsupported elements if you call File::setProperties() with the
218 * same PropertyMap as argument.
219 */
220 StringList &unsupportedData();
221 const StringList &unsupportedData() const;
222
223 /*!
224 * Removes all entries which have an empty value list.
225 */
226 void removeEmpty();
227
228 String toString() const;
229
230 private:
231
232
233 StringList unsupported;
234 };
235
236}
237#endif /* TAGLIB_PROPERTYMAP_H_ */
238