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 32 namespace 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 * - COMPOSERSORT 72 * 73 * Credits: 74 * 75 * - COMPOSER 76 * - LYRICIST 77 * - CONDUCTOR 78 * - REMIXER 79 * - PERFORMER:\<XXXX> 80 * 81 * Other tags: 82 * 83 * - ISRC 84 * - ASIN 85 * - BPM 86 * - COPYRIGHT 87 * - ENCODEDBY 88 * - MOOD 89 * - COMMENT 90 * - MEDIA 91 * - LABEL 92 * - CATALOGNUMBER 93 * - BARCODE 94 * - RELEASECOUNTRY 95 * - RELEASESTATUS 96 * - RELEASETYPE 97 * 98 * MusicBrainz identifiers: 99 * 100 * - MUSICBRAINZ_TRACKID 101 * - MUSICBRAINZ_ALBUMID 102 * - MUSICBRAINZ_RELEASEGROUPID 103 * - MUSICBRAINZ_RELEASETRACKID 104 * - MUSICBRAINZ_WORKID 105 * - MUSICBRAINZ_ARTISTID 106 * - MUSICBRAINZ_ALBUMARTISTID 107 * - ACOUSTID_ID 108 * - ACOUSTID_FINGERPRINT 109 * - MUSICIP_PUID 110 * 111 */ 112 113 class TAGLIB_EXPORT PropertyMap: public SimplePropertyMap 114 { 115 public: 116 117 typedef SimplePropertyMap::Iterator Iterator; 118 typedef SimplePropertyMap::ConstIterator ConstIterator; 119 120 PropertyMap(); 121 122 PropertyMap(const PropertyMap &m); 123 124 /*! 125 * Creates a PropertyMap initialized from a SimplePropertyMap. Copies all 126 * entries from \a m that have valid keys. 127 * Invalid keys will be appended to the unsupportedData() list. 128 */ 129 PropertyMap(const SimplePropertyMap &m); 130 131 virtual ~PropertyMap(); 132 133 /*! 134 * Inserts \a values under \a key in the map. If \a key already exists, 135 * then \a values will be appended to the existing StringList. 136 * The returned value indicates success, i.e. whether \a key is a 137 * valid key. 138 */ 139 bool insert(const String &key, const StringList &values); 140 141 /*! 142 * Replaces any existing values for \a key with the given \a values, 143 * and simply insert them if \a key did not exist before. 144 * The returned value indicates success, i.e. whether \a key is a 145 * valid key. 146 */ 147 bool replace(const String &key, const StringList &values); 148 149 /*! 150 * Find the first occurrence of \a key. 151 */ 152 Iterator find(const String &key); 153 154 /*! 155 * Find the first occurrence of \a key. 156 */ 157 ConstIterator find(const String &key) const; 158 159 /*! 160 * Returns true if the map contains values for \a key. 161 */ 162 bool contains(const String &key) const; 163 164 /*! 165 * Returns true if this map contains all keys of \a other 166 * and the values coincide for that keys. Does not take 167 * the unsupportedData list into account. 168 */ 169 bool contains(const PropertyMap &other) const; 170 171 /*! 172 * Erase the \a key and its values from the map. 173 */ 174 PropertyMap &erase(const String &key); 175 176 /*! 177 * Erases from this map all keys that appear in \a other. 178 */ 179 PropertyMap &erase(const PropertyMap &other); 180 181 /*! 182 * Merge the contents of \a other into this PropertyMap. 183 * If a key is contained in both maps, the values of the second 184 * are appended to that of the first. 185 * The unsupportedData() lists are concatenated as well. 186 */ 187 PropertyMap &merge(const PropertyMap &other); 188 189 /*! 190 * Returns a reference to the value associated with \a key. 191 * 192 * \note: If \a key is not contained in the map, an empty 193 * StringList is returned without error. 194 */ 195 const StringList &operator[](const String &key) const; 196 197 /*! 198 * Returns a reference to the value associated with \a key. 199 * 200 * \note: If \a key is not contained in the map, an empty 201 * StringList is returned. You can also directly add entries 202 * by using this function as an lvalue. 203 */ 204 StringList &operator[](const String &key); 205 206 /*! 207 * Returns true if and only if \a other has the same contents as this map. 208 */ 209 bool operator==(const PropertyMap &other) const; 210 211 /*! 212 * Returns false if and only \a other has the same contents as this map. 213 */ 214 bool operator!=(const PropertyMap &other) const; 215 216 /*! 217 * If a PropertyMap is read from a File object using File::properties(), 218 * the StringList returned from this function will represent metadata 219 * that could not be parsed into the PropertyMap representation. This could 220 * be e.g. binary data, unknown ID3 frames, etc. 221 * You can remove items from the returned list, which tells TagLib to remove 222 * those unsupported elements if you call File::setProperties() with the 223 * same PropertyMap as argument. 224 */ 225 StringList &unsupportedData(); 226 const StringList &unsupportedData() const; 227 228 /*! 229 * Removes all entries which have an empty value list. 230 */ 231 void removeEmpty(); 232 233 String toString() const; 234 235 private: 236 237 238 StringList unsupported; 239 }; 240 241 } 242 #endif /* TAGLIB_PROPERTYMAP_H_ */ 243