LLDB  mainline
FileSpecList.h
Go to the documentation of this file.
1 //===-- FileSpecList.h ------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_CORE_FILESPECLIST_H
10 #define LLDB_CORE_FILESPECLIST_H
11 #if defined(__cplusplus)
12 
13 #include "lldb/Utility/FileSpec.h"
14 
15 #include <vector>
16 
17 #include <cstddef>
18 
19 namespace lldb_private {
20 class Stream;
21 
22 /// \class FileSpecList FileSpecList.h "lldb/Core/FileSpecList.h"
23 /// A file collection class.
24 ///
25 /// A class that contains a mutable list of FileSpec objects.
26 class FileSpecList {
27 public:
28  typedef std::vector<FileSpec> collection;
29  typedef collection::const_iterator const_iterator;
30 
31  /// Default constructor.
32  ///
33  /// Initialize this object with an empty file list.
34  FileSpecList();
35 
36  /// Copy constructor.
37  FileSpecList(const FileSpecList &rhs) = default;
38 
39  /// Move constructor
40  FileSpecList(FileSpecList &&rhs) = default;
41 
42  /// Initialize this object from a vector of FileSpecs
43  FileSpecList(std::vector<FileSpec> &&rhs) : m_files(std::move(rhs)) {}
44 
45  /// Destructor.
46  ~FileSpecList();
47 
48  /// Assignment operator.
49  ///
50  /// Replace the file list in this object with the file list from \a rhs.
51  ///
52  /// \param[in] rhs
53  /// A file list object to copy.
54  ///
55  /// \return
56  /// A const reference to this object.
57  FileSpecList &operator=(const FileSpecList &rhs) = default;
58 
59  /// Move-assignment operator.
60  FileSpecList &operator=(FileSpecList &&rhs) = default;
61 
62  /// Append a FileSpec object to the list.
63  ///
64  /// Appends \a file to the end of the file list.
65  ///
66  /// \param[in] file
67  /// A new file to append to this file list.
68  void Append(const FileSpec &file);
69 
70  /// Append a FileSpec object if unique.
71  ///
72  /// Appends \a file to the end of the file list if it doesn't already exist
73  /// in the file list.
74  ///
75  /// \param[in] file
76  /// A new file to append to this file list.
77  ///
78  /// \return
79  /// \b true if the file was appended, \b false otherwise.
80  bool AppendIfUnique(const FileSpec &file);
81 
82  /// Inserts a new FileSpec into the FileSpecList constructed in-place with
83  /// the given arguments.
84  ///
85  /// \param[in] args
86  /// Arguments to create the FileSpec
87  template <class... Args> void EmplaceBack(Args &&... args) {
88  m_files.emplace_back(std::forward<Args>(args)...);
89  }
90 
91  /// Clears the file list.
92  void Clear();
93 
94  /// Dumps the file list to the supplied stream pointer "s".
95  ///
96  /// \param[in] s
97  /// The stream that will be used to dump the object description.
98  void Dump(Stream *s, const char *separator_cstr = "\n") const;
99 
100  /// Find a file index.
101  ///
102  /// Find the index of the file in the file spec list that matches \a file
103  /// starting \a idx entries into the file spec list.
104  ///
105  /// \param[in] idx
106  /// An index into the file list.
107  ///
108  /// \param[in] file
109  /// The file specification to search for.
110  ///
111  /// \param[in] full
112  /// Should FileSpec::Equal be called with "full" true or false.
113  ///
114  /// \return
115  /// The index of the file that matches \a file if it is found,
116  /// else UINT32_MAX is returned.
117  size_t FindFileIndex(size_t idx, const FileSpec &file, bool full) const;
118 
119  /// Find a compatible file index.
120  ///
121  /// Find the index of a compatible file in the file spec list that matches \a
122  /// file starting \a idx entries into the file spec list. A file is considered
123  /// compatible if:
124  /// - The file matches exactly (only filename if \a file has no directory)
125  /// - If \a file is relative and any file in the list has this same suffix
126  /// - If any file in the list is relative and the relative path is a suffix
127  /// of \a file
128  ///
129  /// This is used to implement better matching for setting breakpoints in
130  /// source files where an IDE might specify a full path when setting the
131  /// breakpoint and debug info contains relative paths, if a user specifies
132  /// a relative path when setting a breakpoint.
133  ///
134  /// \param[in] idx
135  /// An index into the file list.
136  ///
137  /// \param[in] file
138  /// The file specification to search for.
139  ///
140  /// \return
141  /// The index of the file that matches \a file if it is found,
142  /// else UINT32_MAX is returned.
143  size_t FindCompatibleIndex(size_t idx, const FileSpec &file) const;
144 
145  /// Get file at index.
146  ///
147  /// Gets a file from the file list. If \a idx is not a valid index, an empty
148  /// FileSpec object will be returned. The file objects that are returned can
149  /// be tested using FileSpec::operator void*().
150  ///
151  /// \param[in] idx
152  /// An index into the file list.
153  ///
154  /// \return
155  /// A copy of the FileSpec object at index \a idx. If \a idx
156  /// is out of range, then an empty FileSpec object will be
157  /// returned.
158  const FileSpec &GetFileSpecAtIndex(size_t idx) const;
159 
160  /// Get file specification pointer at index.
161  ///
162  /// Gets a file from the file list. The file objects that are returned can
163  /// be tested using FileSpec::operator void*().
164  ///
165  /// \param[in] idx
166  /// An index into the file list.
167  ///
168  /// \return
169  /// A pointer to a contained FileSpec object at index \a idx.
170  /// If \a idx is out of range, then an NULL is returned.
171  const FileSpec *GetFileSpecPointerAtIndex(size_t idx) const;
172 
173  /// Get the memory cost of this object.
174  ///
175  /// Return the size in bytes that this object takes in memory. This returns
176  /// the size in bytes of this object, not any shared string values it may
177  /// refer to.
178  ///
179  /// \return
180  /// The number of bytes that this object occupies in memory.
181  size_t MemorySize() const;
182 
183  bool IsEmpty() const { return m_files.empty(); }
184 
185  /// Get the number of files in the file list.
186  ///
187  /// \return
188  /// The number of files in the file spec list.
189  size_t GetSize() const;
190 
191  bool Insert(size_t idx, const FileSpec &file) {
192  if (idx < m_files.size()) {
193  m_files.insert(m_files.begin() + idx, file);
194  return true;
195  } else if (idx == m_files.size()) {
196  m_files.push_back(file);
197  return true;
198  }
199  return false;
200  }
201 
202  bool Replace(size_t idx, const FileSpec &file) {
203  if (idx < m_files.size()) {
204  m_files[idx] = file;
205  return true;
206  }
207  return false;
208  }
209 
210  bool Remove(size_t idx) {
211  if (idx < m_files.size()) {
212  m_files.erase(m_files.begin() + idx);
213  return true;
214  }
215  return false;
216  }
217 
218  static size_t GetFilesMatchingPartialPath(const char *path, bool dir_okay,
219  FileSpecList &matches);
220 
221  const_iterator begin() const { return m_files.begin(); }
222  const_iterator end() const { return m_files.end(); }
223 
224 protected:
225  collection m_files; ///< A collection of FileSpec objects.
226 };
227 
228 } // namespace lldb_private
229 
230 #endif // #if defined(__cplusplus)
231 #endif // LLDB_CORE_FILESPECLIST_H
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
FileSpec.h