Changeset 681

Timestamp:

05/06/08 20:26:15 (7 months ago)

Author:

mloskot

Message:

Documented liblas::guid class (Ticket #45).

Files:

• trunk/include/liblas/guid.hpp (modified) (26 diffs)

trunk/include/liblas/guid.hpp

@@ -4 +4 @@
  * Project:  libLAS - http://liblas.org - A BSD library for LAS format data.
  * Purpose:  GUID implementation
- * Author:   Mateusz Loskot, mateusz@loskot.net
+ * Author:   Andy Tompkins (modified by Mateusz Loskot)
  *
- * This file has been stolen from <boost/cstdint.hpp> and
- * modified for libLAS purposes.
+ * This file has been stolen from the Boost Vault and
+ * modified for libLAS purposes. Here is the original code posted:
+ * http://lists.boost.org/boost-users/2007/04/27397.php
  * 
  * (C) Copyright 2006 Andy Tompkins.
@@ -76 +77 @@
 namespace liblas {
 
-/// \todo To be documented.
+/// Definition of Globally Unique Identifier type.
+/// The GUID is a 16-byte (128-bit) number.
+/// This class is used to represent value stored as Project Identifier
+/// in public header block (see LASHeader) of a LAS file.
+/// All files in a unique project should have the same value of
+/// the Project Identifier. It is used together with File Source ID to
+/// uniquely identify every LAS, globally.
+///
+/// \see About GUID in Wikipedia http://en.wikipedia.org/wiki/Globally_Unique_Identifier 
 class guid
 {
 public:
 
+    /// Default constructor initializes GUID as null.
+    /// \exception nothrow
+    /// \post guid::is_null() == true.
     guid() /* throw() */
     {
@@ -86 +98 @@
     }
 
+    /// Initializes from textual representation of valid GUID.
+    /// \param str - non-null pointer to string with GUID text.
+    /// \exception std::invalid_argument if construction failed.
+    /// \post guid::is_null() == false.
     explicit guid(char const* const str)
     {
@@ -93 +109 @@
     }
 
+    /// Initializes from textual representation of valid GUID.
+    /// \param str - string with GUID text.
+    /// \exception std::invalid_argument if construction failed.
+    /// \post guid::is_null() == false.
     template <typename ch, typename char_traits, typename alloc>
     explicit guid(std::basic_string<ch, char_traits, alloc> const& str)
@@ -99 +119 @@
     }
 
+    /// Initializes from 4-fields structure.
+    /// \param d1 - field of first 32 bits of GUID number.
+    /// \param d2 - field of subsequent 16 bits of GUID number.
+    /// \param d3 - third field of 16 bits of GUID number.
+    /// \param d4 - last 64 bits of GUID number.
+    /// \exception std::invalid_argument if construction failed.
+    /// \post guid::is_null() == false.
     guid(liblas::uint32_t const& d1, liblas::uint16_t const& d2, liblas::uint16_t const& d3, liblas::uint8_t const (&d4)[8])
     {
@@ -104 +131 @@
     }
 
+    /// Copy constructor.
+    /// \exception nothrow
     guid(guid const& rhs) /* throw() */
     {
@@ -109 +138 @@
     }
 
+    /// Destructor.
+    /// \exception nothrow
     ~guid() /* throw() */
     {}
 
+    /// Assignment operator.
+    /// \exception nothrow
     guid& operator=(guid const& rhs) /* throw() */
     {
@@ -121 +154 @@
     }
 
+    /// Equality operator.
+    /// \exception nothrow
     bool operator==(guid const& rhs) const /* throw() */
     {
@@ -126 +161 @@
     }
 
+    /// Inequality operator.
+    /// \exception nothrow
     bool operator!=(guid const& rhs) const /* throw() */
     {
@@ -131 +168 @@
     }
 
+    /// Less-than operator.
+    /// \param rhs - GUID object on the right-hand side of the comparison.
+    /// \return true if the GUID on the left-hand side is lexicographically less
+    /// than GUID on the right side; false otherwise.
+    /// \exception nothrow
     bool operator<(guid const& rhs) const /* throw() */
     {
@@ -136 +178 @@
     }
     
+    /// More-than operator.
+    /// \param rhs - GUID object on the right-hand side of the comparison.
+    /// \return true if the GUID on the left-hand side is not lexicographically less
+    /// than GUID on the right side; false otherwise.
+    /// \exception nothrow
     bool operator>(guid const& rhs) const /* throw() */
     {
@@ -141 +188 @@
     }
 
+    /// Less-than-or-equal-to operator.
+    /// \param rhs - GUID object on the right-hand side of the comparison.
+    /// \exception nothrow
     bool operator<=(guid const& rhs) const /* throw() */
     {
@@ -146 +196 @@
     }
 
+    /// More-than-or-equal-to operator.
+    /// \param rhs - GUID object on the right-hand side of the comparison.
+    /// \exception nothrow
     bool operator>=(guid const& rhs) const /* throw() */
     {
@@ -151 +204 @@
     }
 
+    /// Test if the GUID object is null GUID or not.
+    /// Null means GUID number value is Zero.
+    /// \return true if the GUID is null; false otherwise
+    /// \exception nothrow
     bool is_null() const /* throw() */
     {
@@ -156 +213 @@
     }
 
+    /// Generate textual representation of the GUID number.
+    /// Specialization for std::string type.
+    /// \return string with textual representation of GUID
+    /// \exception std::runtime_error - thrown on GUID to string conversion failure
+    /// \post guid::to_string().empty() == false.
     std::string to_string() const
     {
@@ -161 +223 @@
     }
     
+    /// Generic generator of textual representation of the GUID number.
+    /// \exception std::runtime_error - thrown on GUID to string conversion failure
+    /// \post guid::to_basic_string().empty() == false.
     template <typename ch, typename char_traits, typename alloc>
     std::basic_string<ch, char_traits, alloc> to_basic_string() const
@@ -172 +237 @@
             throw std::runtime_error("failed to convert guid to string");
         }
+
+        assert(!s.empty());
         return s;
     }
 
+    /// Size of the GUID number in bytes.
+    /// \return The number of bytes is constant for all GUID objects
+    /// and equal to 16 bytes (128-bit number).
     size_t byte_count() const /* throw() */
     {
@@ -180 +250 @@
     }
 
+
+    /// Send bytes of GUID data to sequenec of bytes using given output iterator.
+    /// \exception nothrow
     template <typename ByteOutputIterator>
     void output_bytes(ByteOutputIterator out) const
@@ -186 +259 @@
     }
 
+    /// Separate bytes of GUID data to distinct buffers.
+    /// \param d1 - buffer for first 32 bits of GUID number.
+    /// \param d2 - buffer for 16 bits of second chunk of GUID number.
+    /// \param d3 - buffer for 16 bits of third chunk of GUID number.
+    /// \param d4 - buffer for last 64 bits of GUID number.
+    /// \exception nothrow
     void output_data(liblas::uint32_t& d1, liblas::uint16_t& d2, liblas::uint16_t& d3, liblas::uint8_t (&d4)[8]) const
     {
@@ -217 +296 @@
     }
 
+    /// Null GUID number generator.
+    /// \return null-initialized instance of GUID number.
+    /// \exception nothrow
     static guid const& null() /* throw() */
     {
@@ -223 +305 @@
     }
 
+    /// Random GUID number generator.
+    /// \return random-initialized instance of GUID number.
+    /// \exception nothrow
     static guid create()
     {
@@ -228 +313 @@
     }
     
+    /// Create GUID number based on calculation of SHA1 has for given name.
+    /// \exception std::runtime_error on GUID creation failure.
     static guid create(guid const& namespace_guid, char const* name, int name_length)
     {
@@ -233 +320 @@
     }
 
+    /// Return flag indicating if bracket text form of GUID on output is set.
+    /// \exception nothrow
     static inline bool get_showbraces(std::ios_base & iosbase)
     {
         return (iosbase.iword(get_showbraces_index()) != 0);
     }
+
+    /// Request to bracket text form of GUID on output.
+    /// \exception nothrow
     static inline void set_showbraces(std::ios_base & iosbase, bool showbraces)
     {
@@ -242 +334 @@
     }
 
+    /// Request to bracket text form of GUID on output.
+    /// \exception nothrow
     static inline std::ios_base& showbraces(std::ios_base& iosbase)
     {
@@ -253 +347 @@
     }
     
+    /// Overloaded output stream operator for guid type.
     friend std::ostream& operator<<(std::ostream& os, guid const& g);
+
+    /// Overloaded input stream operator for guid type.
     friend std::istream& operator>>(std::istream& is, guid &g);
 
@@ -303 +400 @@
 
     //random number based
-    static guid create_random_based()
+    static guid create_random_based() // throw()
     {
         guid result;