LLVM API Documentation

StringRef.h

Go to the documentation of this file.
00001 //===--- StringRef.h - Constant String Reference Wrapper --------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 
00010 #ifndef LLVM_ADT_STRINGREF_H
00011 #define LLVM_ADT_STRINGREF_H
00012 
00013 #include <algorithm>
00014 #include <cassert>
00015 #include <cstring>
00016 #include <string>
00017 
00018 namespace llvm {
00019 
00020   /// StringRef - Represent a constant reference to a string, i.e. a character
00021   /// array and a length, which need not be null terminated.
00022   ///
00023   /// This class does not own the string data, it is expected to be used in
00024   /// situations where the character data resides in some other buffer, whose
00025   /// lifetime extends past that of the StringRef. For this reason, it is not in
00026   /// general safe to store a StringRef.
00027   class StringRef {
00028   public:
00029     typedef const char *iterator;
00030     static const size_t npos = ~size_t(0);
00031 
00032   private:
00033     /// The start of the string, in an external buffer.
00034     const char *Data;
00035 
00036     /// The length of the string.
00037     size_t Length;
00038 
00039   public:
00040     /// @name Constructors
00041     /// @{
00042 
00043     /// Construct an empty string ref.
00044     /*implicit*/ StringRef() : Data(0), Length(0) {}
00045 
00046     /// Construct a string ref from a cstring.
00047     /*implicit*/ StringRef(const char *Str) 
00048       : Data(Str), Length(::strlen(Str)) {}
00049  
00050     /// Construct a string ref from a pointer and length.
00051     /*implicit*/ StringRef(const char *_Data, unsigned _Length)
00052       : Data(_Data), Length(_Length) {}
00053 
00054     /// Construct a string ref from an std::string.
00055     /*implicit*/ StringRef(const std::string &Str) 
00056       : Data(Str.c_str()), Length(Str.length()) {}
00057 
00058     /// @}
00059     /// @name Iterators
00060     /// @{
00061 
00062     iterator begin() const { return Data; }
00063 
00064     iterator end() const { return Data + Length; }
00065 
00066     /// @}
00067     /// @name String Operations
00068     /// @{
00069 
00070     /// data - Get a pointer to the start of the string (which may not be null
00071     /// terminated).
00072     const char *data() const { return Data; }
00073 
00074     /// empty - Check if the string is empty.
00075     bool empty() const { return Length == 0; }
00076 
00077     /// size - Get the string size.
00078     size_t size() const { return Length; }
00079 
00080     /// front - Get the first character in the string.
00081     char front() const {
00082       assert(!empty());
00083       return Data[0];
00084     }
00085     
00086     /// back - Get the last character in the string.
00087     char back() const {
00088       assert(!empty());
00089       return Data[Length-1];
00090     }
00091 
00092     /// equals - Check for string equality, this is more efficient than
00093     /// compare() when the relative ordering of inequal strings isn't needed.
00094     bool equals(const StringRef &RHS) const {
00095       return (Length == RHS.Length && 
00096               memcmp(Data, RHS.Data, RHS.Length) == 0);
00097     }
00098 
00099     /// compare - Compare two strings; the result is -1, 0, or 1 if this string
00100     /// is lexicographically less than, equal to, or greater than the \arg RHS.
00101     int compare(const StringRef &RHS) const {
00102       // Check the prefix for a mismatch.
00103       if (int Res = memcmp(Data, RHS.Data, std::min(Length, RHS.Length)))
00104         return Res < 0 ? -1 : 1;
00105 
00106       // Otherwise the prefixes match, so we only need to check the lengths.
00107       if (Length == RHS.Length)
00108         return 0;
00109       return Length < RHS.Length ? -1 : 1;
00110     }
00111 
00112     /// str - Get the contents as an std::string.
00113     std::string str() const { return std::string(Data, Length); }
00114 
00115     /// @}
00116     /// @name Operator Overloads
00117     /// @{
00118 
00119     char operator[](size_t Index) const { 
00120       assert(Index < Length && "Invalid index!");
00121       return Data[Index]; 
00122     }
00123 
00124     /// @}
00125     /// @name Type Conversions
00126     /// @{
00127 
00128     operator std::string() const {
00129       return str();
00130     }
00131 
00132     /// @}
00133     /// @name String Predicates
00134     /// @{
00135 
00136     /// startswith - Check if this string starts with the given \arg Prefix.
00137     bool startswith(const StringRef &Prefix) const { 
00138       return substr(0, Prefix.Length).equals(Prefix);
00139     }
00140 
00141     /// endswith - Check if this string ends with the given \arg Suffix.
00142     bool endswith(const StringRef &Suffix) const {
00143       return slice(size() - Suffix.Length, size()).equals(Suffix);
00144     }
00145 
00146     /// @}
00147     /// @name String Searching
00148     /// @{
00149 
00150     /// find - Search for the character \arg C in the string.
00151     ///
00152     /// \return - The index of the first occurence of \arg C, or npos if not
00153     /// found.
00154     size_t find(char C) const {
00155       for (size_t i = 0, e = Length; i != e; ++i)
00156         if (Data[i] == C)
00157           return i;
00158       return npos;
00159     }
00160 
00161     /// find - Search for the string \arg Str in the string.
00162     ///
00163     /// \return - The index of the first occurence of \arg Str, or npos if not
00164     /// found.
00165     size_t find(const StringRef &Str) const {
00166       size_t N = Str.size();
00167       if (N > Length)
00168         return npos;
00169       for (size_t i = 0, e = Length - N + 1; i != e; ++i)
00170         if (substr(i, N).equals(Str))
00171           return i;
00172       return npos;
00173     }
00174 
00175     /// count - Return the number of occurrences of \arg C in the string.
00176     size_t count(char C) const {
00177       size_t Count = 0;
00178       for (size_t i = 0, e = Length; i != e; ++i)
00179         if (Data[i] == C)
00180           ++Count;
00181       return Count;
00182     }
00183 
00184     /// count - Return the number of non-overlapped occurrences of \arg Str in
00185     /// the string.
00186     size_t count(const StringRef &Str) const {
00187       size_t Count = 0;
00188       size_t N = Str.size();
00189       if (N > Length)
00190         return 0;
00191       for (size_t i = 0, e = Length - N + 1; i != e; ++i)
00192         if (substr(i, N).equals(Str))
00193           ++Count;
00194       return Count;
00195     }
00196 
00197     /// @}
00198     /// @name Substring Operations
00199     /// @{
00200 
00201     /// substr - Return a reference to the substring from [Start, Start + N).
00202     ///
00203     /// \param Start - The index of the starting character in the substring; if
00204     /// the index is npos or greater than the length of the string then the
00205     /// empty substring will be returned.
00206     ///
00207     /// \param N - The number of characters to included in the substring. If N
00208     /// exceeds the number of characters remaining in the string, the string
00209     /// suffix (starting with \arg Start) will be returned.
00210     StringRef substr(size_t Start, size_t N = npos) const {
00211       Start = std::min(Start, Length);
00212       return StringRef(Data + Start, std::min(N, Length - Start));
00213     }
00214 
00215     /// slice - Return a reference to the substring from [Start, End).
00216     ///
00217     /// \param Start - The index of the starting character in the substring; if
00218     /// the index is npos or greater than the length of the string then the
00219     /// empty substring will be returned.
00220     ///
00221     /// \param End - The index following the last character to include in the
00222     /// substring. If this is npos, or less than \arg Start, or exceeds the
00223     /// number of characters remaining in the string, the string suffix
00224     /// (starting with \arg Start) will be returned.
00225     StringRef slice(size_t Start, size_t End) const {
00226       Start = std::min(Start, Length);
00227       End = std::min(std::max(Start, End), Length);
00228       return StringRef(Data + Start, End - Start);
00229     }
00230 
00231     /// split - Split into two substrings around the first occurence of a
00232     /// separator character.
00233     ///
00234     /// If \arg Separator is in the string, then the result is a pair (LHS, RHS)
00235     /// such that (*this == LHS + Separator + RHS) is true and RHS is
00236     /// maximal. If \arg Separator is not in the string, then the result is a
00237     /// pair (LHS, RHS) where (*this == LHS) and (RHS == "").
00238     ///
00239     /// \param Separator - The character to split on.
00240     /// \return - The split substrings.
00241     std::pair<StringRef, StringRef> split(char Separator) const {
00242       size_t Idx = find(Separator);
00243       if (Idx == npos)
00244         return std::make_pair(*this, StringRef());
00245       return std::make_pair(slice(0, Idx), slice(Idx+1, npos));
00246     }
00247 
00248     /// @}
00249   };
00250 
00251   /// @name StringRef Comparison Operators
00252   /// @{
00253 
00254   inline bool operator==(const StringRef &LHS, const StringRef &RHS) {
00255     return LHS.equals(RHS);
00256   }
00257 
00258   inline bool operator!=(const StringRef &LHS, const StringRef &RHS) { 
00259     return !(LHS == RHS);
00260   }
00261   
00262   inline bool operator<(const StringRef &LHS, const StringRef &RHS) {
00263     return LHS.compare(RHS) == -1; 
00264   }
00265 
00266   inline bool operator<=(const StringRef &LHS, const StringRef &RHS) {
00267     return LHS.compare(RHS) != 1; 
00268   }
00269 
00270   inline bool operator>(const StringRef &LHS, const StringRef &RHS) {
00271     return LHS.compare(RHS) == 1; 
00272   }
00273 
00274   inline bool operator>=(const StringRef &LHS, const StringRef &RHS) {
00275     return LHS.compare(RHS) != -1; 
00276   }
00277 
00278   /// @}
00279 
00280 }
00281 
00282 #endif