DownloadQuery filters and sorts DownloadItems.

content/browser/download/download_query.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_
+#define CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_
+#pragma once
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "content/browser/download/download_item.h"
+
+// Filter and sort a vector of DownloadItem*s.
+//
+// The following example copies from |all_items| to |results| those
+// DownloadItem*s whose start time is not 0 or whose id is odd, sorts primarily
+// by bytes received ascending and secondarily by url descending, and limits the
+// results to 20 items. Any number of filter fields or sort rules is
+// permissible. If all sort fields compare two DownloadItems equivalently, then
+// they are sorted by their id ascending or db_handle ascending.
+//
+// DownloadQuery query;
+// CHECK(query.Filter(FILTER_FIELD_START_TIME, 0));
+// bool FilterOutOddDownloads(const DownloadItem& item) {
+//   return 0 == (item.GetId() % 2);
+// }
+// CHECK(query.Filter(base::Bind(&FilterOutOddDownloads)));
+// query.Sort(SORT_FIELD_BYTES_RECEIVED, ASCENDING);
+// query.Sort(SORT_FIELD_URL, DESCENDING);
+// query.Limit(20);
+// DownloadVector all_items, results;
+// query.Search(all_items.begin(), all_items.end(), &results);
+class CONTENT_EXPORT DownloadQuery {
+ public:
+  DownloadQuery();
+  ~DownloadQuery();
+
+  // FilterType is a Callback that takes a DownloadItem and returns true if the
+  // item matches the filter and false otherwise.
+  // query.Filter(base::Bind(&YourFilterFunction));
+  typedef base::Callback<bool(const DownloadItem&)> FilterType;
+
+  enum FilterFieldName {
+    FILTER_FIELD_BYTES_RECEIVED,  // int

[Randy Smith (Not in Mondays), 2011/12/01 19:24:30]

nit, suggestion: I find this type of annotation easier to read if the comments
are lined up.

[benjhayden, 2011/12/02 22:31:53]

Done.

+    FILTER_FIELD_DANGER_ACCEPTED,  // bool
+    FILTER_FIELD_ENDED_AFTER,  // int
+    FILTER_FIELD_ENDED_BEFORE,  // int
+    FILTER_FIELD_END_TIME,  // int
+    FILTER_FIELD_ERROR,  // int
+    FILTER_FIELD_FILENAME,  // string16
+    FILTER_FIELD_FILENAME_REGEX,  // string16
+    FILTER_FIELD_FILE_SIZE,  // int
+    FILTER_FIELD_FILE_SIZE_GREATER,  // int
+    FILTER_FIELD_FILE_SIZE_LESS,  // int
+    FILTER_FIELD_MIME,  // std::string
+    FILTER_FIELD_PAUSED,  // bool
+    FILTER_FIELD_QUERY,  // string16
+    FILTER_FIELD_STARTED_AFTER,  // int
+    FILTER_FIELD_STARTED_BEFORE,  // int
+    FILTER_FIELD_START_TIME,  // int
+    FILTER_FIELD_TOTAL_BYTES,  // int
+    FILTER_FIELD_TOTAL_BYTES_GREATER,  // int
+    FILTER_FIELD_TOTAL_BYTES_LESS,  // int
+    FILTER_FIELD_URL,  // std::string
+    FILTER_FIELD_URL_REGEX,  // std::string
+  };
+
+  // Returns false if |name| is unrecognized or if |value| is the wrong type or
+  // malformed. Otherwise, adds a new filter of type |name| and with value
+  // |value|, and returns true. Search() will filter out all DownloadItem*s that
+  // do not match all filters. Multiple instances of the same FilterFieldName
+  // are allowed, so you can pass two regexes to Filter(URL_REGEX,...) in order
+  // to Search() for items whose url matches both regexes. You can also pass two
+  // different DownloadStates to Filter(), which will cause Search() to filter
+  // out all items.
+  bool Filter(FilterFieldName name, int value);
+  bool Filter(FilterFieldName name, bool value);
+  bool Filter(FilterFieldName name, const std::string& value);
+  bool Filter(FilterFieldName name, const string16& value);
+  void Filter(DownloadStateInfo::DangerType danger);
+  void Filter(DownloadItem::DownloadState state);
+  void Filter(const FilterType& filter);
+
+  enum SortFieldName {
+    SORT_FIELD_BYTES_RECEIVED,
+    SORT_FIELD_DANGER,
+    SORT_FIELD_DANGER_ACCEPTED,
+    SORT_FIELD_END_TIME,
+    SORT_FIELD_ERROR,
+    SORT_FIELD_FILENAME,
+    SORT_FIELD_FILE_SIZE,
+    SORT_FIELD_MIME,
+    SORT_FIELD_PAUSED,
+    SORT_FIELD_START_TIME,
+    SORT_FIELD_STATE,
+    SORT_FIELD_TOTAL_BYTES,
+    SORT_FIELD_URL,
+  };
+
+  enum SortFieldDirection {
+    ASCENDING,
+    DESCENDING,
+  };
+
+  // Adds a new sort field named |name| and sets its direction to |direction|.

[Randy Smith (Not in Mondays), 2011/12/01 19:24:30]

nit: I'm still tripping over the connotations in the comment of "name" vs.
"type".   When I see that something is "named" something, I take the name as
being a pure label, and not having semantic meaning, which isn't true here.  

[benjhayden, 2011/12/02 22:31:53]

I'm open to suggestions.
There's a Callback typedef (currently FilterType), an enum (currently
FilterFieldName), and a method (currently Filter) that all need different but
similar names. This parameter's name is tied to the enum's name. If I rename the
enum to FilterType, then what should I rename the Callback typdef?

+  // After filtering DownloadItem*s, Search() will sort the results primarily by
+  // the sort field from the first call to Sort(), secondarily by the sort field
+  // from the second call to Sort(), and so on. For example, if the
+  // InputIterator passed to Search() yields four DownloadItems {id:0, error:0,
+  // start_time:0}, {id:1, error:0, start_time:1}, {id:2, error:1,
+  // start_time:0}, {id:3, error:1, start_time:1}, and Sort is called twice,
+  // once with (SORT_FIELD_ERROR, ASCENDING) then with (SORT_FIELD_START_TIME,
+  // DESCENDING), then Search() will return items ordered 1,0,3,2.
+  void Sort(SortFieldName name, SortFieldDirection direction);
+
+  // Limit the size of search results to |limit|.
+  void Limit(size_t limit) { limit_ = limit; }
+
+  typedef std::vector<DownloadItem*> DownloadVector;
+
+  // Filters DownloadItem*s from |iter| to |last| into |results|, sorts
+  // |results|, and limits the size of |results|. |results| must be non-NULL.
+  template <typename InputIterator>
+  void Search(InputIterator iter, const InputIterator last,
+              DownloadVector* results) const;
+
+  // Returns true if |item| matches all set filter fields; returns false if any
+  // filter fields have been set that the item does not match.
+  bool Matches(const DownloadItem& item) const;
+
+ private:
+  struct SortField;
+  class DownloadComparator;
+  typedef std::vector<FilterType> FilterFieldVector;
+  typedef std::vector<SortField> SortFieldVector;
+
+  bool FilterRegex(const std::string& regex_str,
+      const base::Callback<std::string(const DownloadItem&)>& accessor);
+
+  FilterFieldVector filter_fields_;
+  SortFieldVector sort_fields_;
+  size_t limit_;
+
+  DISALLOW_COPY_AND_ASSIGN(DownloadQuery);
+};
+
+#endif  // CONTENT_BROWSER_DOWNLOAD_DOWNLOAD_QUERY_H_