X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=include%2Fllvm%2FObject%2FYAML.h;h=89fe5047a86e91c697cc0edf841ccad2ef75fe1b;hb=814b52710ad53e6d613aebaca8df8e962a432f50;hp=7f59dd1cbc8bd12fc4392be10b8ecdf16f0ac449;hpb=0d861a24d87306543e9dc3657584bb9b26d110cc;p=oota-llvm.git

diff --git a/include/llvm/Object/YAML.h b/include/llvm/Object/YAML.h
index 7f59dd1cbc8..89fe5047a86 100644
--- a/include/llvm/Object/YAML.h
+++ b/include/llvm/Object/YAML.h
@@ -21,9 +21,48 @@ namespace llvm {
 namespace object {
 namespace yaml {
 
-/// In an object file this is just a binary blob. In an yaml file it is an hex
-/// string. Using this avoid having to allocate temporary strings.
+/// \brief Specialized YAMLIO scalar type for representing a binary blob.
+///
+/// A typical use case would be to represent the content of a section in a
+/// binary file.
+/// This class has custom YAMLIO traits for convenient reading and writing.
+/// It renders as a string of hex digits in a YAML file.
+/// For example, it might render as `DEADBEEFCAFEBABE` (YAML does not
+/// require the quotation marks, so for simplicity when outputting they are
+/// omitted).
+/// When reading, any string whose content is an even number of hex digits
+/// will be accepted.
+/// For example, all of the following are acceptable:
+/// `DEADBEEF`, `"DeADbEeF"`, `"\x44EADBEEF"` (Note: '\x44' == 'D')
+///
+/// A significant advantage of using this class is that it never allocates
+/// temporary strings or buffers for any of its functionality.
+///
+/// Example:
+///
+/// The YAML mapping:
+/// \code
+/// Foo: DEADBEEFCAFEBABE
+/// \endcode
+///
+/// Could be modeled in YAMLIO by the struct:
+/// \code
+/// struct FooHolder {
+///   BinaryRef Foo;
+/// };
+/// namespace llvm {
+/// namespace yaml {
+/// template <>
+/// struct MappingTraits<FooHolder> {
+///   static void mapping(IO &IO, FooHolder &FH) {
+///     IO.mapRequired("Foo", FH.Foo);
+///   }
+/// };
+/// } // end namespace yaml
+/// } // end namespace llvm
+/// \endcode
 class BinaryRef {
+  friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
   /// \brief Either raw binary data, or a string of hex bytes (must always
   /// be an even number of characters).
   ArrayRef<uint8_t> Data;
@@ -43,13 +82,6 @@ public:
       return Data.size() / 2;
     return Data.size();
   }
-  bool operator==(const BinaryRef &Ref) {
-    // Special case for default constructed BinaryRef.
-    if (Ref.Data.empty() && Data.empty())
-      return true;
-
-    return Ref.DataIsHexString == DataIsHexString && Ref.Data == Data;
-  }
   /// \brief Write the contents (regardless of whether it is binary or a
   /// hex string) as binary to the given raw_ostream.
   void writeAsBinary(raw_ostream &OS) const;
@@ -60,6 +92,14 @@ public:
   void writeAsHex(raw_ostream &OS) const;
 };
 
+inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
+  // Special case for default constructed BinaryRef.
+  if (LHS.Data.empty() && RHS.Data.empty())
+    return true;
+
+  return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
+}
+
 }
 }