banshee r3233 - in trunk/musicbrainz-sharp: . docs/en docs/en/MusicBrainz src/MusicBrainz src/MusicBrainz/MusicBrainz tests tests/MusicBrainz.Tests
- From: scottp svn gnome org
- To: svn-commits-list gnome org
- Subject: banshee r3233 - in trunk/musicbrainz-sharp: . docs/en docs/en/MusicBrainz src/MusicBrainz src/MusicBrainz/MusicBrainz tests tests/MusicBrainz.Tests
- Date: Wed, 13 Feb 2008 17:36:07 +0000 (GMT)
Author: scottp
Date: Wed Feb 13 17:36:06 2008
New Revision: 3233
URL: http://svn.gnome.org/viewvc/banshee?rev=3233&view=rev
Log:
* src/MusicBrainz/MusicBrainz/Utilities.cs: Fixed bug in EnumToString.
* src/MusicBrainz/MusicBrainz/Query.cs: Minor changes
* docs/en/MusicBrainz.xml, docs/en/MusicBrainz/Release.xml,
docs/en/MusicBrainz/Query`1.xml, docs/en/MusicBrainz/Track.xml,
docs/en/MusicBrainz/Artist.xml,
docs/en/MusicBrainz/MusicBrainzObject.xml,
docs/en/MusicBrainz/Label.xml, docs/en/index.xml: Updated docs
* tests/MusicBrainz.Tests/ReleaseTests.cs,
tests/MusicBrainz.Tests/ArtistTests.cs: Made to use new QuerySingle
syntax.
Modified:
trunk/musicbrainz-sharp/ChangeLog
trunk/musicbrainz-sharp/docs/en/MusicBrainz.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/Artist.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/Label.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/MusicBrainzObject.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/Query`1.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/Release.xml
trunk/musicbrainz-sharp/docs/en/MusicBrainz/Track.xml
trunk/musicbrainz-sharp/docs/en/index.xml
trunk/musicbrainz-sharp/src/MusicBrainz/ChangeLog
trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Query.cs
trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Utilities.cs
trunk/musicbrainz-sharp/tests/ChangeLog
trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ArtistTests.cs
trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ReleaseTests.cs
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz.xml Wed Feb 13 17:36:06 2008
@@ -1,6 +1,23 @@
<Namespace Name="MusicBrainz">
<Docs>
- <summary>To be added.</summary>
- <remarks>To be added.</remarks>
+ <summary>
+ <para>An object-oriented API for retrieving data from the MusicBrainz web service.</para>
+ </summary>
+ <remarks>
+ <para>
+ Get the title of a CD in the CDRom tray:
+ <example><code lang="C#">
+Release r = Release.GetFromDevice (cd_device); // Where cd_device is something like "/dev/cdrom/" or "E:\"
+Console.WriteLine (r.Title)
+</code></example>
+ </para>
+ <para>
+ Search for artists named "Justice":
+ <example><code lang="C#">
+foreach (Artist a in Artist.Query ("Justice"))
+ Console.WriteLine (string.Format ("{0} ({1}% relevance)", a.Name, a.Score));
+</code></example>
+ </para>
+ </remarks>
</Docs>
</Namespace>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/Artist.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/Artist.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/Artist.xml Wed Feb 13 17:36:06 2008
@@ -17,18 +17,7 @@
</remarks>
</Docs>
<Members>
-
-
-
-
-
-
-
-
-
-
-
- <Member MemberName="ArtistReleaseType">
+ <Member MemberName="ArtistReleaseType">
<MemberSignature Language="C#" Value="public MusicBrainz.ArtistReleaseType ArtistReleaseType { set; get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>MusicBrainz.ArtistReleaseType</ReturnType></ReturnValue>
@@ -53,7 +42,8 @@
{...}
</code></example></para>
</remarks></Docs>
- </Member><Member MemberName="DefaultArtistReleaseType">
+ </Member>
+ <Member MemberName="DefaultArtistReleaseType">
<MemberSignature Language="C#" Value="public static MusicBrainz.ArtistReleaseType DefaultArtistReleaseType;" />
<MemberType>Field</MemberType>
<ReturnValue><ReturnType>MusicBrainz.ArtistReleaseType</ReturnType></ReturnValue>
@@ -61,7 +51,8 @@
<example><code lang="C#">new ArtistReleaseType(ReleaseStatus.Official, false)
</code></example>
This means Official Releases which are authored by the Artist alone.</remarks></Docs>
- </Member><Member MemberName="Get">
+ </Member>
+ <Member MemberName="Get">
<MemberSignature Language="C#" Value="public static MusicBrainz.Artist Get (string mbid);" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>MusicBrainz.Artist</ReturnType></ReturnValue>
@@ -71,7 +62,8 @@
See http://wiki.musicbrainz.org/ArtistID
</block>
</remarks></Docs>
- </Member><Member MemberName="op_Implicit">
+ </Member>
+ <Member MemberName="op_Implicit">
<MemberSignature Language="C#" Value="public static string op_Implicit (MusicBrainz.Artist a);" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>System.String</ReturnType></ReturnValue>
@@ -104,13 +96,15 @@
These two queries are substantively different. See http://wiki.musicbrainz.org/TextSearchSyntax for more information.
</para>
</remarks></Docs>
- </Member><Member MemberName="Query">
+ </Member>
+ <Member MemberName="Query">
<MemberSignature Language="C#" Value="public static MusicBrainz.Query<MusicBrainz.Artist> Query (string name);" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>MusicBrainz.Query<MusicBrainz.Artist></ReturnType></ReturnValue>
<Parameters><Parameter Name="name" Type="System.String" /></Parameters>
<Docs><param name="name">The name of an artist.</param><summary>Query for Artists by name.</summary><returns>An enumerable Query of results.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="QueryLucene">
+ </Member>
+ <Member MemberName="QueryLucene">
<MemberSignature Language="C#" Value="public static MusicBrainz.Query<MusicBrainz.Artist> QueryLucene (string lucene_query);" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>MusicBrainz.Query<MusicBrainz.Artist></ReturnType></ReturnValue>
@@ -120,28 +114,14 @@
See http://wiki.musicbrainz.org/TextSearchSyntax
</block>
</remarks></Docs>
- </Member><Member MemberName="QueryLuceneSingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Artist QueryLuceneSingle (string lucene_query);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Artist</ReturnType></ReturnValue>
- <Parameters><Parameter Name="lucene_query" Type="System.String" /></Parameters>
- <Docs><param name="lucene_query">A lucene text query.</param><summary>Query for an Artist by lucene text query.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>
- <block subset="none" type="note">
-See http://wiki.musicbrainz.org/TextSearchSyntax
-</block>
- </remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Artist QuerySingle (string name);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Artist</ReturnType></ReturnValue>
- <Parameters><Parameter Name="name" Type="System.String" /></Parameters>
- <Docs><param name="name">The name of the artist.</param><summary>Query for an Artist by name.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="Releases">
+ </Member>
+ <Member MemberName="Releases">
<MemberSignature Language="C#" Value="public System.Collections.Generic.List<MusicBrainz.Release> Releases { get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>System.Collections.Generic.List<MusicBrainz.Release></ReturnType></ReturnValue>
<Docs><summary>A list of the Artist's Releases. The Releases in the list will be determined by the Artist's <see cref="M:MusicBrainz.Artist.ArtistReleaseType" />.</summary><value>A List of <see cref="T:MusicBrainz.Release" />s. If there are no releases, an empty List.</value><remarks>This property will never be null.</remarks></Docs>
- </Member><Member MemberName="Type">
+ </Member>
+ <Member MemberName="Type">
<MemberSignature Language="C#" Value="public MusicBrainz.ArtistType Type { get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>MusicBrainz.ArtistType</ReturnType></ReturnValue>
@@ -150,10 +130,12 @@
See http://wiki.musicbrainz.org/ArtistType
</block>
</remarks></Docs>
- </Member><Member MemberName="url_extension">
- <MemberSignature Language="C#" Value="protected override string url_extension { get; };" />
+ </Member>
+ <Member MemberName="UrlExtension">
+ <MemberSignature Language="C#" Value="protected override string UrlExtension { get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>System.String</ReturnType></ReturnValue>
<Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="UrlExtension"><MemberSignature Language="C#" Value="protected override string UrlExtension { get; };" /><MemberType>Property</MemberType><ReturnValue><ReturnType>System.String</ReturnType></ReturnValue><Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs></Member></Members>
+ </Member>
+ </Members>
</Type>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/Label.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/Label.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/Label.xml Wed Feb 13 17:36:06 2008
@@ -94,22 +94,6 @@
See http://wiki.musicbrainz.org/TextSearchSyntax
</block>
</remarks></Docs>
- </Member><Member MemberName="QueryLuceneSingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Label QueryLuceneSingle (string lucene_query);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Label</ReturnType></ReturnValue>
- <Parameters><Parameter Name="lucene_query" Type="System.String" /></Parameters>
- <Docs><param name="lucene_query">A lucene text query.</param><summary>Query for a Label by lucene text query.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>
- <block subset="none" type="note">
-See http://wiki.musicbrainz.org/TextSearchSyntax
-</block>
- </remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Label QuerySingle (string name);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Label</ReturnType></ReturnValue>
- <Parameters><Parameter Name="name" Type="System.String" /></Parameters>
- <Docs><param name="name">The name of the label.</param><summary>Query for a Label by name.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>To be added.</remarks></Docs>
</Member><Member MemberName="Type">
<MemberSignature Language="C#" Value="public MusicBrainz.LabelType Type { get; };" />
<MemberType>Property</MemberType>
@@ -119,10 +103,5 @@
See http://wiki.musicbrainz.org/LabelType
</block>
</remarks></Docs>
- </Member><Member MemberName="url_extension">
- <MemberSignature Language="C#" Value="protected override string url_extension { get; };" />
- <MemberType>Property</MemberType>
- <ReturnValue><ReturnType>System.String</ReturnType></ReturnValue>
- <Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs>
</Member><Member MemberName="UrlExtension"><MemberSignature Language="C#" Value="protected override string UrlExtension { get; };" /><MemberType>Property</MemberType><ReturnValue><ReturnType>System.String</ReturnType></ReturnValue><Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs></Member></Members>
</Type>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/MusicBrainzObject.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/MusicBrainzObject.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/MusicBrainzObject.xml Wed Feb 13 17:36:06 2008
@@ -204,17 +204,6 @@
<block subset="none" type="note">
See http://wiki.musicbrainz.org/ArtistTrackRelationship, http://wiki.musicbrainz.org/ReleaseTrackRelationship, http://wiki.musicbrainz.org/LabelTrackRelationship, and http://wiki.musicbrainz.org/TrackTrackRelationship
</block></remarks></Docs>
- </Member><Member MemberName="url_extension">
- <MemberSignature Language="C#" Value="protected abstract string url_extension { get; };" />
- <MemberType>Property</MemberType>
- <ReturnValue>
- <ReturnType>System.String</ReturnType>
- </ReturnValue>
- <Docs>
- <summary>To be added.</summary>
- <value>To be added.</value>
- <remarks>To be added.</remarks>
- </Docs>
</Member><Member MemberName="UrlExtension">
<MemberSignature Language="C#" Value="protected abstract string UrlExtension { get; };" />
<MemberType>Property</MemberType>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/Query`1.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/Query`1.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/Query`1.xml Wed Feb 13 17:36:06 2008
@@ -28,13 +28,25 @@
A Query is attainted by calling one of the static Query() methods on one of the concrete MusicBrainz resources: <see cref="T:MusicBrainz.Artist" />, <see cref="T:MusicBrainz.Release" />, <see cref="T:MusicBrainz.Track" />, or <see cref="T:MusicBrainz.Label" />. Results are ordered in descending relevance.
</para>
<para>
-In this example, we query for artists named "Justice" and print the names and MBIDs of those Artists which are sufficiently relevant:
+In this example, we query for all artists named "Justice" and print their names and MBIDs:
<example><code lang="C#">
foreach(Artist a in Artist.Query("Justice"))
- if(a.Score > 90)
- Console.WriteLine("{0} ({1})", a.Name, a.MBID);
- else
- break;
+ Console.WriteLine("{0} ({1})", a.Name, a.MBID);
+ </code></example></para>
+ <para>A Query can also be implicitly cast as the type for which you are querying. So if you would like just the first result of a Query, you can simple do this:
+<example><code lang="C#">
+Release r = Release.Query("Fiji Baby");
+Console.WriteLine(r.Artist.Name);
+ </code></example>
+Note: this will return null if no results are returned.
+</para>
+ <para>It is often the case that you will only care about results at or above a certain level of relevance. For convienience, you can iterate over a Query's Best(int) method. This will return only the results with scores at or above the specified threshold. Or you can call Best() with no parameters, which will only return results with a 100 relevancy score.
+<example><code lang="C#">
+foreach(Artist a in Artist.Query("Me First").Best(70)) // Only returns results whose score is 70 or better
+ Console.WriteLine(a.Name);
+
+foreach(Release r in Release.Query("Are a Drag").Best()) // Only returns results with a score of 100
+ Console.WriteLine(r.Title);
</code></example></para>
<para>A Query does not actually contact the MusicBrainz servers until its results are accessed. For example, the following code does not involve a XMLWebService request:
<example><code lang="C#">
@@ -51,6 +63,8 @@
Track t = q[0];
// or
List<Track> results = q.ToList();
+// or
+Track t = q;
</code></example></para>
<para>
Be aware that the MusicBrainz XMLWebService can only return results 100 at a time, so each 100 iterations over a Query will result in another call to the MusicBrainz server, which means a significant delay in execution. For this reason it is important to break out of iterating over a Query when you are able.
@@ -58,23 +72,20 @@
</remarks>
</Docs>
<Members>
-
-
-
-
-
<Member MemberName="Count">
<MemberSignature Language="C#" Value="public int Count { get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>System.Int32</ReturnType></ReturnValue>
<Docs><summary>The number of results.</summary><value>The total number of results to the query.</value><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="GetEnumerator">
+ </Member>
+ <Member MemberName="GetEnumerator">
<MemberSignature Language="C#" Value="public System.Collections.Generic.IEnumerator<T> GetEnumerator ();" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>System.Collections.Generic.IEnumerator<T></ReturnType></ReturnValue>
<Parameters />
<Docs><summary>To be added.</summary><returns>To be added.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="Item">
+ </Member>
+ <Member MemberName="Item">
<MemberSignature Language="C#" Value="public T this[int i] { get; };" />
<MemberType>Property</MemberType>
<ReturnValue><ReturnType>T</ReturnType></ReturnValue>
@@ -87,7 +98,7 @@
Query<Artist> q = Artist.Query("The Wallflowers");
Artist a = q.Count > 0 ? q[0] : null;
</code></example>
-Note: this is how <see cref="M:MusicBrainz.Artist.QuerySingle" /> works</para>
+Note: this is how Query's implicit conversion to T works</para>
<para>
In this example, we iterate over the first 10 results of a Query with a for loop and the indexer:
<example><code lang="C#">
@@ -98,26 +109,68 @@
}
</code></example></para>
</remarks></Docs>
- </Member><Member MemberName="System.Collections.IEnumerable.GetEnumerator">
- <MemberSignature Language="C#" Value="System.Collections.IEnumerator IEnumerable.GetEnumerator ();" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>System.Collections.IEnumerator</ReturnType></ReturnValue>
- <Parameters />
- <Docs><summary>To be added.</summary><returns>To be added.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="ToArray">
+ </Member>
+ <Member MemberName="ToArray">
<MemberSignature Language="C#" Value="public T[] ToArray ();" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>T[]</ReturnType></ReturnValue>
<Parameters />
- <Docs><summary>To be added.</summary><returns>To be added.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="ToList">
+ <Docs><summary>Convert a Query to an array of results.</summary><returns>An array of all the results.</returns><remarks>
+ <para>
+The MusicBrainz XMLWebService only returns results 100 at a time, so iterating over each 100 results incures another XML transaction, i.e. a significant delay in execution. Since the ToArray() method must iterate over all results, it is highly advisible to use another method whenever possible (such as the foreach statement, or a for loop and the indexer).
+</para>
+ </remarks></Docs>
+ </Member>
+ <Member MemberName="ToList">
<MemberSignature Language="C#" Value="public System.Collections.Generic.List<T> ToList ();" />
<MemberType>Method</MemberType>
<ReturnValue><ReturnType>System.Collections.Generic.List<T></ReturnType></ReturnValue>
<Parameters />
- <Docs><summary>Convert a Query into a List of results.</summary><returns>A List of all the Query results.</returns><remarks>
+ <Docs><summary>Returns a List of all results.</summary><returns>A List of all the Query results.</returns><remarks>
+ <para>
+The MusicBrainz XMLWebService only returns results 100 at a time, so iterating over each 100 results incures another XML transaction, i.e. a significant delay in execution. Since the ToList() method must iterate over all results, it is advisible to use another method whenever possible (such as the foreach statement, or a for loop and the indexer). If you are only interested in results with a relavance score higher than, say, 50, you should use the overload ToList(int) which takes a score threshold.
+</para>
+ </remarks></Docs>
+ </Member>
+ <Member MemberName="Best">
+ <MemberSignature Language="C#" Value="public System.Collections.Generic.IEnumerable<T> Best ();" />
+ <MemberType>Method</MemberType>
+ <ReturnValue><ReturnType>System.Collections.Generic.IEnumerable<T></ReturnType></ReturnValue>
+ <Parameters />
+ <Docs><summary>Returns only results with a <see cref="M:MusicBrainz.MusicBrainzObject.Score" /> of 100 (the highest).</summary><returns>Results with a 100 relevancy score.</returns><remarks>This method is logically identical to calling Query.Best(100);</remarks></Docs>
+ </Member>
+ <Member MemberName="Best">
+ <MemberSignature Language="C#" Value="public System.Collections.Generic.IEnumerable<T> Best (int score_threshold);" />
+ <MemberType>Method</MemberType>
+ <ReturnValue><ReturnType>System.Collections.Generic.IEnumerable<T></ReturnType></ReturnValue>
+ <Parameters><Parameter Name="score_threshold" Type="System.Int32" /></Parameters>
+ <Docs><param name="score_threshold">The relevancy threshold. Any result with a <see cref="M:MusicBrainz.MusicBrainzObject.Score" /> lower than this number will not be returned.</param><summary>Returns only results with a <see cref="M:MusicBrainz.MusicBrainzObject.Score" /> at or above the specified relevancy threshold.</summary><returns>Results at or above the specified relevancy.</returns><remarks>If you only want results of a given quality, this is the perfered method for retrieving them. This example iterates over all artists with a score of 50 or better when querying for "Dylan":
+<example><code lang="C#">
+foreach(Artist a in Artist.Query("Dylan").Best(50))
+ Console.WriteLine(a.Name);
+ </code></example></remarks></Docs>
+ </Member>
+ <Member MemberName="op_Implicit">
+ <MemberSignature Language="C#" Value="public static T op_Implicit (MusicBrainz.Query<T> query);" />
+ <MemberType>Method</MemberType>
+ <ReturnValue><ReturnType>T</ReturnType></ReturnValue>
+ <Parameters><Parameter Name="query" Type="MusicBrainz.Query<T>" /></Parameters>
+ <Docs><param name="query">To be added.</param><summary>The first result.</summary><returns>The first result of the Query or null if there are no results.
+<block subset="none" type="note"><para>
+This result may not nessisarily have a <see cref="M:MusicBrainz.MusicBrainzObject.Score" /> of 100. While this will be the most relevant result, it's relevancy to the query may still be weak.
+ </para></block></returns><remarks>This operator makes it easy to get the first result form a query:
+<example><code lang="C#">
+Artist a = Artist.Query("The Scissor Sisters");
+ </code></example></remarks></Docs>
+ </Member>
+ <Member MemberName="ToList">
+ <MemberSignature Language="C#" Value="public System.Collections.Generic.List<T> ToList (int score_threshold);" />
+ <MemberType>Method</MemberType>
+ <ReturnValue><ReturnType>System.Collections.Generic.List<T></ReturnType></ReturnValue>
+ <Parameters><Parameter Name="score_threshold" Type="System.Int32" /></Parameters>
+ <Docs><param name="score_threshold">The relevancy threshold. Any result with a <see cref="M:MusicBrainz.MusicBrainzObject.Score" /> below this number will not be included in the List.</param><summary>Returns a List of results above the specified relevance threshold.</summary><returns>A List of results at or above the specified relevancy threshold.</returns><remarks>
<para>
-The MusicBrainz XMLWebService only returns results 100 at a time, so iterating over each 100 results incures another XML transaction, i.e. a significant delay in execution. Since the ToList() method must iterate over all results, it is advisible to use another method whenever possible (such as the foreach statement, or a for loop and the indexer). If you are only interested in results with a relavance score higher than, say, 50, you should use a loop and then break from it when the results are no longer of sufficient relevance.
+The MusicBrainz XMLWebService only returns results 100 at a time, so iterating over each 100 results incures another XML transaction, i.e. a significant delay in execution. The lower the threshold you specify, the more results will be included. Be aware that too low a threshold can cause multiple XML transaction (one transaction per 100 results) and can slow down your program.
</para>
</remarks></Docs>
</Member>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/Release.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/Release.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/Release.xml Wed Feb 13 17:36:06 2008
@@ -137,17 +137,6 @@
p.Artist = "some artist";
Release.Query(p);
</code></example></remarks></Docs>
- </Member><Member MemberName="QueryFromDeviceSingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Release QueryFromDeviceSingle (string device);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue>
- <Parameters><Parameter Name="device" Type="System.String" /></Parameters>
- <Docs><param name="device">The path to a device (CDRom drive) with a disc.</param><summary>Query for the Release whose Disc is in the specified device.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>This method is shorthand for:
-<example><code lang="C#">
-ReleaseQueryParameters p = new ReleaseQueryParameters();
-p.DiscID = Disc.GetFromDevice(@"E:\").ID; // Where E:\ is the path to a CDRom drive
-Release.QuerySingle(p);
- </code></example></remarks></Docs>
</Member><Member MemberName="QueryLucene">
<MemberSignature Language="C#" Value="public static MusicBrainz.Query<MusicBrainz.Release> QueryLucene (string lucene_query);" />
<MemberType>Method</MemberType>
@@ -158,45 +147,6 @@
See http://wiki.musicbrainz.org/TextSearchSyntax
</block>
</remarks></Docs>
- </Member><Member MemberName="QueryLuceneSingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Release QueryLuceneSingle (string lucene_query);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue>
- <Parameters><Parameter Name="lucene_query" Type="System.String" /></Parameters>
- <Docs><param name="lucene_query">A lucene text query.</param><summary>Query for a Release by lucene text query.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>
- <block subset="none" type="note">
-See http://wiki.musicbrainz.org/TextSearchSyntax
-</block>
- </remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Release QuerySingle (MusicBrainz.ReleaseQueryParameters parameters);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue>
- <Parameters><Parameter Name="parameters" Type="MusicBrainz.ReleaseQueryParameters" /></Parameters>
- <Docs><param name="parameters">The parameters of the query.</param><summary>Query for a Release parametrically.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Release QuerySingle (string title);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue>
- <Parameters><Parameter Name="title" Type="System.String" /></Parameters>
- <Docs><param name="title">The title of the release.</param><summary>Query for a Release by title.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>This overload is shorthand for:
-<example><code lang="C#">
-ReleaseQueryParameters p = new ReleaseQueryParameters();
-p.Title = "title";
-Release.QuerySingle(p);
- </code></example></remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Release QuerySingle (string title, string artist);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue>
- <Parameters><Parameter Name="title" Type="System.String" /><Parameter Name="artist" Type="System.String" /></Parameters>
- <Docs><param name="title">The title of the release.</param><param name="artist">The name of the release's artist.</param><summary>Query for a Release by title and artist.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>This overload is shorthand for:
-<example><code lang="C#">
-ReleaseQueryParameters p = new ReleaseQueryParameters ();
-p.Title = "title";
-p.Artist = "artist";
-Release.QuerySingle(p);
- </code></example></remarks></Docs>
</Member><Member MemberName="Script">
<MemberSignature Language="C#" Value="public string Script { get; };" />
<MemberType>Property</MemberType>
@@ -229,10 +179,5 @@
See http://wiki.musicbrainz.org/ReleaseType
</block>
</remarks></Docs>
- </Member><Member MemberName="url_extension">
- <MemberSignature Language="C#" Value="protected override string url_extension { get; };" />
- <MemberType>Property</MemberType>
- <ReturnValue><ReturnType>System.String</ReturnType></ReturnValue>
- <Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="UrlExtension"><MemberSignature Language="C#" Value="protected override string UrlExtension { get; };" /><MemberType>Property</MemberType><ReturnValue><ReturnType>System.String</ReturnType></ReturnValue><Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs></Member></Members>
+ </Member><Member MemberName="UrlExtension"><MemberSignature Language="C#" Value="protected override string UrlExtension { get; };" /><MemberType>Property</MemberType><ReturnValue><ReturnType>System.String</ReturnType></ReturnValue><Docs><summary>To be added.</summary><value>To be added.</value><remarks>To be added.</remarks></Docs></Member><Member MemberName="QueryFromDevice"><MemberSignature Language="C#" Value="public static MusicBrainz.Release QueryFromDevice (string device);" /><MemberType>Method</MemberType><ReturnValue><ReturnType>MusicBrainz.Release</ReturnType></ReturnValue><Parameters><Parameter Name="device" Type="System.String" /></Parameters><Docs><param name="device">To be added.</param><summary>To be added.</summary><returns>To be added.</returns><remarks>To be added.</remarks></Docs></Member></Members>
</Type>
Modified: trunk/musicbrainz-sharp/docs/en/MusicBrainz/Track.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/MusicBrainz/Track.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/MusicBrainz/Track.xml Wed Feb 13 17:36:06 2008
@@ -133,45 +133,6 @@
See http://wiki.musicbrainz.org/TextSearchSyntax
</block>
</remarks></Docs>
- </Member><Member MemberName="QueryLuceneSingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Track QueryLuceneSingle (string lucene_query);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Track</ReturnType></ReturnValue>
- <Parameters><Parameter Name="lucene_query" Type="System.String" /></Parameters>
- <Docs><param name="lucene_query">A lucene text query.</param><summary>Query for a Track by lucene text query.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>
- <block subset="none" type="note">
-See http://wiki.musicbrainz.org/TextSearchSyntax
-</block>
- </remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Track QuerySingle (MusicBrainz.TrackQueryParameters parameters);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Track</ReturnType></ReturnValue>
- <Parameters><Parameter Name="parameters" Type="MusicBrainz.TrackQueryParameters" /></Parameters>
- <Docs><param name="parameters">The parameters of the query.</param><summary>Query for a Track parameterically.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>To be added.</remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Track QuerySingle (string title);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Track</ReturnType></ReturnValue>
- <Parameters><Parameter Name="title" Type="System.String" /></Parameters>
- <Docs><param name="title">The title of the track.</param><summary>Query for a Track by title.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>This override is shorthand for:
-<example><code lang="C#">
-TrackQueryParameters p = new TrackQueryParameters();
-p.Title = "some title";
-Track.QuerySingle(p);
- </code></example></remarks></Docs>
- </Member><Member MemberName="QuerySingle">
- <MemberSignature Language="C#" Value="public static MusicBrainz.Track QuerySingle (string title, string artist);" />
- <MemberType>Method</MemberType>
- <ReturnValue><ReturnType>MusicBrainz.Track</ReturnType></ReturnValue>
- <Parameters><Parameter Name="title" Type="System.String" /><Parameter Name="artist" Type="System.String" /></Parameters>
- <Docs><param name="title">The title of the track.</param><param name="artist">The name of the track's artist.</param><summary>Query for a Track by title and artist.</summary><returns>The first (most relevant) result from the query. If no results are returned, null.</returns><remarks>This override is shorthand for:
-<example><code lang="C#">
-TrackQueryParameters p = new TrackQueryParameters();
-p.Title = "some title";
-p.Artist = "some artist";
-Track.QuerySingle(p);
- </code></example></remarks></Docs>
</Member><Member MemberName="Releases">
<MemberSignature Language="C#" Value="public System.Collections.Generic.List<MusicBrainz.Release> Releases { get; };" />
<MemberType>Property</MemberType>
Modified: trunk/musicbrainz-sharp/docs/en/index.xml
==============================================================================
--- trunk/musicbrainz-sharp/docs/en/index.xml (original)
+++ trunk/musicbrainz-sharp/docs/en/index.xml Wed Feb 13 17:36:06 2008
@@ -34,9 +34,7 @@
<Type Name="ReleaseFormat" />
<Type Name="ReleaseQueryParameters" />
<Type Name="ReleaseStatus" />
- <Type Name="ReleaseStatuses" />
<Type Name="ReleaseType" />
- <Type Name="ReleaseTypes" />
<Type Name="Track" />
<Type Name="TrackQueryParameters" />
<Type Name="UrlRelation" />
Modified: trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Query.cs
==============================================================================
--- trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Query.cs (original)
+++ trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Query.cs Wed Feb 13 17:36:06 2008
@@ -82,8 +82,13 @@
public List<T> ToList()
{
- List<T> list = new List<T>(Count);
- foreach(T result in this)
+ return ToList(0);
+ }
+
+ public List<T> ToList(int score_threshold)
+ {
+ List<T> list = new List<T>(score_threshold == 0 ? Count : 0);
+ foreach(T result in Best(score_threshold))
list.Add(result);
return list;
}
@@ -111,10 +116,10 @@
return Best(100);
}
- public IEnumerable<T> Best(int score)
+ public IEnumerable<T> Best(int score_threshold)
{
foreach(T result in this) {
- if(result.Score < score)
+ if(result.Score < score_threshold)
yield break;
yield return result;
}
@@ -122,6 +127,7 @@
public static implicit operator T(Query<T> query)
{
+ query.limit = 1;
return query.Count > 0 ? query[0] : null;
}
}
Modified: trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Utilities.cs
==============================================================================
--- trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Utilities.cs (original)
+++ trunk/musicbrainz-sharp/src/MusicBrainz/MusicBrainz/Utilities.cs Wed Feb 13 17:36:06 2008
@@ -17,9 +17,11 @@
{
string str = enumeration.ToString();
StringBuilder builder = new StringBuilder(str.Length);
+ builder.Append(str[0]);
for(int i = 1; i < str.Length; i++) {
- if(str[i] >= 'A' && str[i] <= 'Z')
+ if(str[i] >= 'A' && str[i] <= 'Z') {
builder.Append('-');
+ }
builder.Append(str[i]);
}
return builder.ToString();
Modified: trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ArtistTests.cs
==============================================================================
--- trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ArtistTests.cs (original)
+++ trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ArtistTests.cs Wed Feb 13 17:36:06 2008
@@ -31,7 +31,7 @@
[Test]
public void QuerySingle()
{
- Artist result = Artist.QuerySingle(goodshirt_name);
+ Artist result = Artist.Query(goodshirt_name);
Assert.IsNotNull(result);
Assert.AreEqual(goodshirt_mbid, result.MBID);
}
@@ -47,7 +47,7 @@
[Test]
public void QuerySingleFail()
{
- Artist result = Artist.QuerySingle("MusicBrainzTestThisShouldFail");
+ Artist result = Artist.Query("MusicBrainzTestThisShouldFail");
Assert.IsNull(result);
}
@@ -68,7 +68,7 @@
[Test]
public void QuerySingleAndCheckDefaultReleaseCount()
{
- Artist result = Artist.QuerySingle(goodshirt_name);
+ Artist result = Artist.Query(goodshirt_name);
Assert.AreEqual(result.Releases.Count, 2);
}
@@ -139,7 +139,7 @@
[Test]
public void QuerySingleAndCheckBeginDateAndEndDate()
{
- Artist artist = Artist.QuerySingle("The Beatles");
+ Artist artist = Artist.Query("The Beatles");
Assert.IsNotNull(artist);
Assert.AreEqual(artist.BeginDate, "1957");
Assert.AreEqual(artist.EndDate, "1970-04-10");
@@ -158,7 +158,7 @@
public void TestArgumentNullException()
{
try {
- Artist a = Artist.QuerySingle(null);
+ Artist a = Artist.Query(null);
throw new Exception();
} catch (ArgumentNullException e) {
Assert.AreEqual(e.ParamName, "name");
Modified: trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ReleaseTests.cs
==============================================================================
--- trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ReleaseTests.cs (original)
+++ trunk/musicbrainz-sharp/tests/MusicBrainz.Tests/ReleaseTests.cs Wed Feb 13 17:36:06 2008
@@ -93,7 +93,7 @@
[Test]
public void QuerySingleByName()
{
- Release result = Release.QuerySingle(fiji_baby_name);
+ Release result = Release.Query(fiji_baby_name);
Assert.IsNotNull(result);
Assert.AreEqual(result.MBID, fiji_baby_mbid);
}
@@ -101,7 +101,7 @@
[Test]
public void QuerySingleFail()
{
- Release result = Release.QuerySingle("MusicBrainzTestThisShouldFail");
+ Release result = Release.Query("MusicBrainzTestThisShouldFail");
Assert.IsNull(result);
}
@@ -134,7 +134,7 @@
public void QuerySingleAndCheckTrackLevelRels1()
{
xml_request_count = 0;
- Release release = Release.QuerySingle("Love Their Country", "Me First and the Gimme Gimmes");
+ Release release = Release.Query("Love Their Country", "Me First and the Gimme Gimmes");
Assert.IsTrue(release.Tracks[0].TrackRelations.Count > 0);
Assert.AreEqual(xml_request_count, 2);
}
@@ -143,7 +143,7 @@
public void QuerySingleAndCheckTrackLevelRels2()
{
xml_request_count = 0;
- Release release = Release.QuerySingle(fiji_baby_name);
+ Release release = Release.Query(fiji_baby_name);
Assert.IsTrue(release.Tracks[0].TrackRelations.Count == 0);
Assert.AreEqual(xml_request_count, 2);
}
@@ -163,7 +163,7 @@
[Test]
public void QuerySingleAndCheckEvents()
{
- Release release = Release.QuerySingle(fiji_baby_name);
+ Release release = Release.Query(fiji_baby_name);
Assert.AreEqual(release.Events.Count, 1);
Assert.AreEqual(release.Events[0].Country, "NZ");
Assert.AreEqual(release.Events[0].Date, "2004");
@@ -191,7 +191,7 @@
[Test]
public void QuerySingleAndCheckDiscs()
{
- Release release = Release.QuerySingle(fiji_baby_name);
+ Release release = Release.Query(fiji_baby_name);
Assert.AreEqual(release.Discs.Count, 1);
Assert.AreEqual(release.Discs[0].ID, "p_R7uoqwl1zVO2UtXliPnky1Ov8-");
Assert.AreEqual(release.Discs[0].Sectors, 167522);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
