Add symtab/LineInformation.h

docs/symtabAPI/developer/API.rst

@@ -20,6 +20,7 @@ SymtabAPI
   emitWin.h
   Function.h
   indexed_modules.h
+  LineInformation.h
   LinkMap.h
   Object-elf.h
   Object.h

docs/symtabAPI/developer/LineInformation.h.rst

@@ -0,0 +1,38 @@
+.. _`sec-dev:LineInformation.h`:
+
+LineInformation.h
+#################
+
+.. cpp:namespace:: Dyninst::SymtabAPI::dev
+
+.. cpp:class:: LineInformation final : private RangeLookupTypes<Statement>::type
+
+  .. cpp:member:: StringTablePtr strings_
+
+  .. cpp:function:: void dump()
+
+      Dumps a debug representation of the line map.
+
+  .. cpp:function:: StringTablePtr getStrings()
+  .. cpp:function:: void setStrings(StringTablePtr strings_)
+
+
+  .. cpp:function:: bool addLine(unsigned int fileIndex, unsigned int lineNo, unsigned int lineOffset, \
+                                 Offset lowInclusiveAddr, Offset highExclusiveAddr)
+
+  .. cpp:function:: bool addLine(const std::string &lineSource, unsigned int lineNo, unsigned int lineOffset, \
+                                 Offset lowInclusiveAddr, Offset highExclusiveAddr)
+
+      This method adds a new line to the line Map. ``lineSource`` represents the source file name.
+      ``lineNo`` represents the line number.
+
+  .. cpp:function:: bool addAddressRange(Offset lowInclusiveAddr, Offset highExclusiveAddr, const char* lineSource, \
+                                         unsigned int lineNo, unsigned int lineOffset = 0);
+
+      This method adds an address range ``[lowInclusiveAddr, highExclusiveAddr)`` for the line with line number ``lineNo``
+      in source file ``lineSource``.
+
+  .. cpp:function:: void addLineInfo(LineInformation *lineInfo)
+
+  .. cpp:function:: std::pair<const_line_info_iterator, const_line_info_iterator> range(std::string const& file, const unsigned int lineNo) const
+  .. cpp:function:: std::pair<const_line_info_iterator, const_line_info_iterator> equal_range(std::string const& file) const

docs/symtabAPI/public/LineInformation.h.rst

@@ -1,70 +1,75 @@
+.. _`sec:LineInformation.h`:
+
 LineInformation.h
-=================
+#################
 
 .. cpp:namespace:: Dyninst::SymtabAPI
 
-Class LineInformation
----------------------
+.. cpp:class:: LineInformation final : private RangeLookupTypes<Statement>::type
+
+  **Mappings from a line number within a source to the address ranges**
+
+  .. cpp:type:: RangeLookupTypes< Statement> traits
+  .. cpp:type:: RangeLookupTypes< Statement >::type impl_t
+  .. cpp:type:: impl_t::index<Statement::addr_range>::type::const_iterator const_iterator
+  .. cpp:type:: impl_t::index<Statement::line_info>::type::const_iterator const_line_info_iterator
+  .. cpp:type:: traits::value_type Statement_t
+
+  .. cpp:function:: LineInformation()
+  .. cpp:function:: ~LineInformation() = default
+
+  .. cpp:function:: bool getSourceLines(Offset addressInRange, std::vector<Statement_t>& lines)
+
+      Returns in ``lines`` the source file names and line numbers corresponding to the address, ``addressInRange``.
+
+      Returns ``true`` if at least one source was found.
+
+  .. cpp:function:: bool getSourceLines(Offset addressInRange, std::vector<Statement>& lines)
+
+      Returns in ``lines`` the source file names and line numbers corresponding to the address, ``addressInRange``.
+
+      Returns ``true`` if at least one source was found.
+
+  .. cpp:function:: bool getAddressRanges(const char* lineSource, unsigned int LineNo, std::vector<AddressRange>& ranges)
+
+      Returns the address ranges in ``ranges`` corresponding to the line with line number ``lineNo`` in the source file ``lineSource``.
 
-This class represents an entire line map for a module. This contains
-mappings from a line number within a source to the address ranges.
+      Searches within this line map.
 
-.. code-block:: cpp
+      Returns ``true`` if at least one range was found.
 
-    bool getAddressRanges(const char * lineSource, unsigned int LineNo,
-    std::vector<AddressRange> & ranges)
+  .. cpp:function:: const_line_info_iterator begin_by_source() const
 
-This methos returns the address ranges in ``ranges`` corresponding to
-the line with line number ``lineNo`` in the source file ``lineSource``.
-Searches within this line map. Return ``true`` if at least one address
-range corresponding to the line number was found and returns ``false``
-if none found.
+      Returns an iterator pointing to the beginning of the underlying source files for the module.
 
-.. code-block:: cpp
+  .. cpp:function:: const_line_info_iterator end_by_source() const
 
-    bool getSourceLines(Offset addressInRange, std::vector<Statement *> & lines) bool getSourceLines(Offset addressInRange,
-    std::vector<LineNoTuple> & lines)
+      Returns an iterator marking the end of the sequence provided by :cpp:func:`begin_by_source`.
 
-These methods returns the source file names and line numbers
-corresponding to the given address ``addressInRange``. Searches within
-this line map. Return ``true`` if at least one tuple corresponding to
-the offset was found and returns ``false`` if none found. Note that the
-order of arguments is reversed from the corresponding interfaces in
-``Module`` and ``Symtab``.
+  .. cpp:function:: LineInformation::const_iterator begin() const
 
-.. code-block:: cpp
+      Returns an iterator pointing to the beginning of the line information for the module.
 
-    bool addLine(const char * lineSource, unsigned int lineNo, unsigned int
-    lineOffset, Offset lowInclusiveAddr, Offset highExclusiveAddr)
+      This is useful for iterating over the entire line information present in a module.
 
-This method adds a new line to the line Map. ``lineSource`` represents
-the source file name. ``lineNo`` represents the line number.
+  .. cpp:function:: LineInformation::const_iterator end() const
 
-.. code-block:: cpp
+      Returns an iterator marking the end of the sequence provided by :cpp:func:`begin`.
 
-    bool addAddressRange(Offset lowInclusiveAddr, Offset highExclusiveAddr,
-    const char* lineSource, unsigned int lineNo, unsigned int lineOffset = 0);
+  .. cpp:function:: const_iterator find(Offset addressInRange) const
 
-This method adds an address range
-``[lowInclusiveAddr, highExclusiveAddr)`` for the line with line number
-``lineNo`` in source file ``lineSource``.
+      Returns an iterator to the line map entry starting at the address, ``addressInRange``,
+      covered by this line map.
 
-.. code-block:: cpp
+      Returns :cpp:func:`end` if not found.
 
-    LineInformation::const_iterator begin() const
+  .. cpp:function:: const_iterator find(Offset addressInRange, const_iterator hint) const
 
-This method returns an iterator pointing to the beginning of the line
-information for the module. This is useful for iterating over the entire
-line information present in a module. An example described in Section
-`7.3 <#subsec:LineNoIterating>`__ gives more information on how to use
-``begin()`` for iterating over the line information.
+      Returns an iterator to the line map entry starting at the address, ``addressInRange``,
+      covered by this line map starting at the position in ``hint``.
 
-.. code-block:: cpp
+      Returns :cpp:func:`end` if not found.
 
-    LineInformation::const_iterator end() const
+  .. cpp:function:: unsigned getSize() const
 
-This method returns an iterator pointing to the end of the line
-information for the module. This is useful for iterating over the entire
-line information present in a module. An example described in Section
-`7.3 <#subsec:LineNoIterating>`__ gives more information on how to use
-``end()`` for iterating over the line information.
+      Returns the number of entries in this map.