1/*
2 * MusicBrainz -- The Internet music metadatabase
3 *
4 * Copyright (C) 2006 Lukas Lalinsky
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but 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 02110-1301 USA
19 *
20 *
21 */
22
23#ifndef __MUSICBRAINZ3_ARTIST_H__
24#define __MUSICBRAINZ3_ARTIST_H__
25
26#include <string>
27#include <vector>
28#include <musicbrainz3/musicbrainz.h>
29#include <musicbrainz3/entity.h>
30#include <musicbrainz3/lists.h>
31
32namespace MusicBrainz
33{
34
35 /**
36 * Represents an artist.
37 *
38 * Artists in MusicBrainz can have a type. Currently, this type can
39 * be either Person or Group for which the following URIs are assigned:
40 *
41 * - \a "http://musicbrainz.org/ns/mmd-1.0#Person"
42 * - \a "http://musicbrainz.org/ns/mmd-1.0#Group"
43 *
44 * Use the \a Artist::TYPE_PERSON and \a Artist::TYPE_GROUP constants for comparison.
45 */
46 class MB_API Artist : public Entity
47 {
48 public:
49
50 static const std::string TYPE_PERSON;
51 static const std::string TYPE_GROUP;
52
53 /**
54 * Constructor.
55 *
56 * @param id a string containing an absolute URI
57 * @param type a string containing an absolute URI
58 * @param name a string containing the artist's name
59 * @param sortName a string containing the artist's sort name
60 */
61 Artist(const std::string &id = "", const std::string &type = "",
62 const std::string &name = "", const std::string &sortName = "");
63
64 /**
65 * Destructor.
66 */
67 virtual ~Artist();
68
69 /**
70 * Returns the artist's type.
71 *
72 * @return a string containing an absolute URI
73 */
74 std::string getType() const;
75
76 /**
77 * Sets the artist's type.
78 *
79 * @param type a string containing an absolute URI
80 */
81 void setType(const std::string &type);
82
83 /**
84 * Returns the artist's name.
85 *
86 * @return a string containing the artist's name, or empty string
87 */
88 std::string getName() const;
89
90 /**
91 * Sets the artist's name.
92 *
93 * @param name a string containing the artist's name
94 */
95 void setName(const std::string &name);
96
97 /**
98 * Returns the artist's sort name.
99 *
100 * <p>The sort name is the artist's name in a special format which
101 * is better suited for lexicographic sorting. The MusicBrainz
102 * style guide specifies this format.</p>
103 *
104 * @see <a href="http://musicbrainz.org/style.html">The MusicBrainz Style Guidelines</a>
105 */
106 std::string getSortName() const;
107
108 /**
109 * Sets the artist's sort name.
110 *
111 * @param sortName: a string containing the artist's sort name
112 *
113 * @see #getSortName
114 */
115 void setSortName(const std::string &sortName);
116
117 /**
118 * Returns the disambiguation attribute.
119 *
120 * This attribute may be used if there is more than one artist
121 * with the same name. In this case, disambiguation attributes
122 * are added to the artists' names to keep them apart.
123 *
124 * For example, there are at least three bands named 'Vixen'.
125 * Each band has a different disambiguation in the MusicBrainz
126 * database, like 'Hip-hop' or 'all-female rock/glam band'.
127 *
128 * @return a disambiguation string
129 *
130 * @see getUniqueName
131 */
132 std::string getDisambiguation() const;
133
134 /**
135 * Sets the disambiguation attribute.
136 *
137 * @param disambiguation a disambiguation string
138 *
139 * @see getDisambiguation, getUniqueName
140 */
141 void setDisambiguation(const std::string &disambiguation);
142
143 /**
144 * Returns a unique artist name (using disambiguation).
145 *
146 * This method returns the artist name together with the
147 * disambiguation attribute in parenthesis if it exists.
148 * Example: 'Vixen (Hip-hop)'.
149 *
150 * @return a string containing the unique name
151 *
152 * @see getDisambiguation
153 */
154 std::string getUniqueName() const;
155
156 /**
157 * Returns the birth/foundation date.
158 *
159 * The definition of the \e begin \e date depends on the artist's
160 * type. For persons, this is the day of birth, for groups it
161 * is the day the group was founded.
162 *
163 * The returned date has the format "YYYY", "YYYY-MM", or
164 * "YYYY-MM-DD", depending on how much detail is known.
165 *
166 * @return a string containing the date
167 *
168 * @see getType
169 */
170 std::string getBeginDate() const;
171
172 /**
173 * Sets the begin/foundation date.
174 *
175 * @param dateStr a date string
176 *
177 * @see getBeginDate
178 */
179 void setBeginDate(const std::string &dateStr);
180
181 /**
182 * Get the death/dissolving date.
183 *
184 * The definition of the \e end \e date depends on the artist's
185 * type. For persons, this is the day of death, for groups it
186 * is the day the group was dissolved.
187 *
188 * @return a string containing a date
189 *
190 * @see getBeginDate
191 */
192 std::string getEndDate() const;
193
194 /**
195 * Sets the death/dissolving date.
196 *
197 * @param dateStr a string containing a date
198 *
199 * @see: setEndDate, getBeginDate
200 */
201 void setEndDate(const std::string &dateStr);
202
203 /**
204 * Returns a list of releases from this artist.
205 *
206 * This may also include releases where this artist isn't the
207 * \e main artist but has just contributed one or more tracks
208 * (aka VA-Releases).
209 *
210 * @return: a list of pointers to Release objects
211 */
212 ReleaseList &getReleases();
213
214 /**
215 * Returns number of releases.
216 *
217 * This is equivalent to \c getReleases().size()
218 *
219 * @return an int containing number of releases
220 *
221 * @see getReleases
222 */
223 int getNumReleases() const;
224
225 /**
226 * Returns an release specified by index.
227 *
228 * This is equivalent to \c getReleases()[index]
229 *
230 * @return a pointer to Release instance
231 *
232 * @see getReleases
233 */
234 Release *getRelease(int index);
235
236 /**
237 * Adds a release to this artist's list of releases.
238 *
239 * @param release a pointer to Release object
240 */
241 void addRelease(Release *release);
242
243 /**
244 * Returns the offset of the release list.
245 *
246 * This is used if the track list is incomplete (ie. the web
247 * service only returned part of the tracks on this release).
248 * Note that the offset value is zero-based, which means track
249 * \a 0 is the first track.
250 *
251 * @return an integer containing the offset
252 *
253 * @see getReleases
254 */
255 int getReleasesOffset() const;
256
257 /**
258 * Sets the offset of the release list.
259 *
260 * @param offset an integer containing the offset
261 *
262 * @see getReleasesOffset
263 */
264 void setReleasesOffset(const int offset);
265
266 /**
267 * Returns the number of existing releases.
268 *
269 * This may or may not match with the number of elements that
270 * getReleases and getNumReleases returns. If the count is higher than
271 * the list, it indicates that the list is incomplete.
272 *
273 * @return an integer containing the count
274 *
275 * @see getReleases
276 */
277 int getReleasesCount() const;
278
279 /**
280 * Sets the count of the release list.
281 *
282 * @param count an integer containing the count
283 *
284 * @see getReleasesCount
285 */
286 void setReleasesCount(const int count);
287
288 /**
289 * Returns the list of aliases for this artist.
290 *
291 * @return a list of pointers to ArtistAlias objects
292 */
293 ArtistAliasList &getAliases();
294
295 /**
296 * Returns number of aliases.
297 *
298 * This is equivalent to \c getAliases().size()
299 *
300 * @return an int containing number of aliases
301 *
302 * @see getAliases
303 */
304 int getNumAliases() const;
305
306 /**
307 * Returns alias specified by index.
308 *
309 * This is equivalent to \c getAliases()[index]
310 *
311 * @return a pointer to ArtistAlias instance
312 *
313 * @see getAliases
314 */
315 ArtistAlias *getAlias(int index);
316
317 /**
318 * Adds an alias for this artist.
319 *
320 * @param alias a pointer to ArtistAlias object
321 */
322 void addAlias(ArtistAlias *alias);
323
324 private:
325
326 class ArtistPrivate;
327 ArtistPrivate *d;
328 };
329
330}
331
332#endif
333