1//===-- Declaration.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_SYMBOL_DECLARATION_H
10#define LLDB_SYMBOL_DECLARATION_H
11
12#include "lldb/Utility/FileSpec.h"
13#include "lldb/lldb-private.h"
14
15namespace lldb_private {
16
17/// \class Declaration Declaration.h "lldb/Core/Declaration.h"
18/// A class that describes the declaration location of a
19///        lldb object.
20///
21/// The declarations include the file specification, line number, and the
22/// column info and can help track where functions, blocks, inlined functions,
23/// types, variables, any many other debug core objects were declared.
24class Declaration {
25public:
26  /// Default constructor.
27  Declaration() = default;
28
29  /// Construct with file specification, and optional line and column.
30  ///
31  /// \param[in] file_spec
32  ///     The file specification that describes where this was
33  ///     declared.
34  ///
35  /// \param[in] line
36  ///     The line number that describes where this was declared. Set
37  ///     to zero if there is no line number information.
38  ///
39  /// \param[in] column
40  ///     The column number that describes where this was declared.
41  ///     Set to zero if there is no column number information.
42  Declaration(const FileSpec &file_spec, uint32_t line = 0,
43              uint16_t column = LLDB_INVALID_COLUMN_NUMBER)
44      : m_file(file_spec), m_line(line), m_column(column) {}
45
46  /// Construct with a pointer to another Declaration object.
47  Declaration(const Declaration *decl_ptr)
48      : m_line(0), m_column(LLDB_INVALID_COLUMN_NUMBER) {
49    if (decl_ptr)
50      *this = *decl_ptr;
51  }
52
53  /// Clear the object's state.
54  ///
55  /// Sets the file specification to be empty, and the line and column to
56  /// zero.
57  void Clear() {
58    m_file.Clear();
59    m_line = 0;
60    m_column = 0;
61  }
62
63  /// Compare two declaration objects.
64  ///
65  /// Compares the two file specifications from \a lhs and \a rhs. If the file
66  /// specifications are equal, then continue to compare the line number and
67  /// column numbers respectively.
68  ///
69  /// \param[in] lhs
70  ///     The Left Hand Side const Declaration object reference.
71  ///
72  /// \param[in] rhs
73  ///     The Right Hand Side const Declaration object reference.
74  ///
75  /// \return
76  ///     -1 if lhs < rhs
77  ///     0 if lhs == rhs
78  ///     1 if lhs > rhs
79  static int Compare(const Declaration &lhs, const Declaration &rhs);
80
81  /// Checks if this object has the same file and line as another declaration
82  /// object.
83  ///
84  /// \param[in] declaration
85  ///     The const Declaration object to compare with.
86  ///
87  /// \return
88  ///     Returns \b true if \b declaration is at the same file and
89  ///     line, \b false otherwise.
90  bool FileAndLineEqual(const Declaration &declaration) const;
91
92  /// Dump a description of this object to a Stream.
93  ///
94  /// Dump a description of the contents of this object to the supplied stream
95  /// \a s.
96  ///
97  /// \param[in] s
98  ///     The stream to which to dump the object description.
99  void Dump(Stream *s, bool show_fullpaths) const;
100
101  bool DumpStopContext(Stream *s, bool show_fullpaths) const;
102
103  /// Get accessor for file specification.
104  ///
105  /// \return
106  ///     A reference to the file specification object.
107  FileSpec &GetFile() { return m_file; }
108
109  /// Get const accessor for file specification.
110  ///
111  /// \return
112  ///     A const reference to the file specification object.
113  const FileSpec &GetFile() const { return m_file; }
114
115  /// Get accessor for the declaration line number.
116  ///
117  /// \return
118  ///     Non-zero indicates a valid line number, zero indicates no
119  ///     line information is available.
120  uint32_t GetLine() const { return m_line; }
121
122  /// Get accessor for the declaration column number.
123  ///
124  /// \return
125  ///     Non-zero indicates a valid column number, zero indicates no
126  ///     column information is available.
127  uint16_t GetColumn() const { return m_column; }
128
129  /// Convert to boolean operator.
130  ///
131  /// This allows code to check a Declaration object to see if it
132  /// contains anything valid using code such as:
133  ///
134  /// \code
135  /// Declaration decl(...);
136  /// if (decl)
137  /// { ...
138  /// \endcode
139  ///
140  /// \return
141  ///     A \b true if both the file_spec and the line are valid,
142  ///     \b false otherwise.
143  explicit operator bool() const { return IsValid(); }
144
145  bool IsValid() const {
146    return m_file && m_line != 0 && m_line != LLDB_INVALID_LINE_NUMBER;
147  }
148
149  /// Get the memory cost of this object.
150  ///
151  /// \return
152  ///     The number of bytes that this object occupies in memory.
153  ///     The returned value does not include the bytes for any
154  ///     shared string values.
155  size_t MemorySize() const;
156
157  /// Set accessor for the declaration file specification.
158  ///
159  /// \param[in] file_spec
160  ///     The new declaration file specification.
161  void SetFile(const FileSpec &file_spec) { m_file = file_spec; }
162
163  /// Set accessor for the declaration line number.
164  ///
165  /// \param[in] line
166  ///     Non-zero indicates a valid line number, zero indicates no
167  ///     line information is available.
168  void SetLine(uint32_t line) { m_line = line; }
169
170  /// Set accessor for the declaration column number.
171  ///
172  /// \param[in] column
173  ///     Non-zero indicates a valid column number, zero indicates no
174  ///     column information is available.
175  void SetColumn(uint16_t column) { m_column = column; }
176
177protected:
178  /// The file specification that points to the source file where the
179  /// declaration occurred.
180  FileSpec m_file;
181  /// Non-zero values indicates a valid line number, zero indicates no line
182  /// number information is available.
183  uint32_t m_line = 0;
184  /// Non-zero values indicates a valid column number, zero indicates no column
185  /// information is available.
186  uint16_t m_column = LLDB_INVALID_COLUMN_NUMBER;
187};
188
189bool operator==(const Declaration &lhs, const Declaration &rhs);
190
191} // namespace lldb_private
192
193#endif // LLDB_SYMBOL_DECLARATION_H
194