Skip to content

Using Data

Jump to bottom
Scott Godin edited this page Nov 12, 2021 · 1 revision

The Data class encapsulates a buffer of bytes. It is similar in functionality to many common string classes, except that it operates on collections of bytes instead of collections of characters. In particular, Data is meant to operate on buffers that may or may not contain binary data. That said, there are a number of operations on Data which are written with manipulation of text in mind, and many methods go out of their way to ensure that the buffer is often null-terminated. It's a bit schizophrenic that way. (ed.: the null termination is useful when rooting about in the debugger).

Table of Contents

Buffer Management

Management Models

At any given time, a Data is associated with a single buffer which contains the bytes inside the Data. This buffer may be owned by the Data object itself, or owned by an external party. Additionally, data owned by an external party can be considered changeable or unchangeable.

Sharing Style Buffer Ownership Buffer Mutable?
Share External to Data class No
Borrow External to Data class Yes
Take Owned by Data class Yes

If a Data containing an immutable buffer (i.e. Sharing Mode is Share) is changed, then a new buffer is allocated by the Data, the contents of the existing (immutable) buffer are copied into it, and the modification is performed on the new buffer. This newly allocated buffer is owned by the Data.

If a modification is performed on a Data which requires more space than is available in the underlying buffer, then a larger buffer is allocated, the existing bytes are copied into the new buffer, and the modification is performed on the new buffer. If the old buffer was owned by the Data, it will be deallocated.

Note that all deallocation performed by the Data uses delete[]; consequently, any data owned by the Data (e.g. Sharing Mode is Take) must be allocated from the normal heap using new[], lest you anger the portability gods.

Finally, users of Data should note that a Data created from a buffer with Share or Borrow sharing must not outlive the buffer itself.

Foo

This section isn't even finished enough to have a proper name. This is probably a good place to discuss stack based Data buffers and DataStream use. 

 void reserve(size_type capacity);

Creating a Data

Data conveniently has fifteen non-deprecated constructors for your creation pleasure. The default constructor will ultimately cause the Data to allocate its own internal memory. The copy constuctor does pretty much what you expect it to do.

Creating from Another Type

Data will take a variety of different kinds of types in its constructor and convert them into the string representation of those types.

Conversion from null-terminated c-style string: 

 char *mySignedCharPtr = "Hello";
 resip::Data data1(mySignedCharPtr); // data1 contains "Hello"

Conversion from null-terminated c-style string of unsigned characters (for the criminally insane): 

 unsigned char *myUnsignedCharPtr = "Hej";
 resip::Data data2(myUnsignedCharPtr); // data2 contains "Hej"

Conversion from STL string: 

 std::string myString = "Hola";
 resip::Data data3(myString); // data3 contains "Hola"

Conversion from integer: 

 int myInt = -75;
 resip::Data data4(myInt); // data4 contains "-75"

Conversion from unsigned long integer: 

 unsigned long myUnsignedLong = 12345;
 resip::Data data5(myUnsignedLong); // data5 contains "12345"

Conversion from unsigned integer: 

 unsigned int myUnsignedInt = 75;
 resip::Data data6(myUnsignedInt); // data6 contains "75"

Conversion from double takes an optional precision parameter which indicates the number of digits after the decimal point. Trailing zeros are omitted. If not specified, the default precision is 4. 

 double myDouble = 7.12345;
 resip::Data data7(myDouble); // data7 contains "7.1234"
 resip::Data data8(myDouble, resip::Data::TwoDigitPrecision); // data8 contains "7.12"
 resip::Data data9(myDouble, resip::Data::SixDigitPrecision); // data9 contains "7.12345"

Conversion from boolean: 

 bool myBool = true;
 resip::Data data10(myBool); // data10 contains "true"

Conversion from character: 

 char myChar = 'a';
 resip::Data data11(myChar); // data11 contains "a"

If none of the preceding methods give you the tools that you need to convert from another data type, you can use the "Data::from" class method to create the Data you want. The only requirement is that the type that you're creating the Data from has an associated streaming operator. This is particularly useful if you want to create a Data from a non-primitive data type. 

 ComplexDataThingy foo;
 resip::Data data12 = Data::from(foo);

Creating from an Existing Buffer

The easiest way to create a Data from an existing buffer is to pass in a buffer and the number of bytes of meaningful data that exist in the buffer. This constructor operates in "Take" mode -- the Data will copy the passed-in buffer immediately. 

 char buffer[2048];
 int bytes = read(fd, buffer, sizeof(buffer));
 resip::Data myData(buffer, bytes);

Alternately, you can explicitly indicate the sharing mode desired; once again, the length indictated is the number of meaninful bytes already present in the buffer, not the total length of the buffer. No constructor yet exists which allows you to indicate both the number of meaningful bytes and the total length of the buffer; if you have a need for such a constructor, though, it should be easy to add one. (ed. allocate the desired size buffer and append the bytes you want) 

 char buffer[2048];
 int bytes = read(fd, buffer, sizeof(buffer));
 resip::Data myData(resip::Data::Borrow, buffer, bytes);

If you are creating a Data from a c-style null-terminated string, you are given the option of indicating a sharing mode also. Be very, very careful that your c-style string is null terminated if you use this constructor. 

 char myChar[] = "Hello";
 resip::Data myData(resip::Data::Borrow, myChar);

Finally, you can create a Data from another Data with an explicit allocation type. This is kind of copy-contstructor-ish, except that the compiler won't call it for you: 

 resip::Data* myData = new resip::Data("I'm a teapot");
 resip::Data* myOtherData = new resip::Data(resip::Data::Share, *myData);

Data Comparisons

This section is not yet finished. 

 bool operator==(const Data& rhs) const;
 bool operator==(const char* rhs) const;
 bool operator!=(const Data& rhs) const;
 bool operator!=(const char* rhs) const;
 bool operator<(const Data& rhs) const;
 bool operator<=(const Data& rhs) const;
 bool operator<(const char* rhs) const;
 bool operator<=(const char* rhs) const;
 bool operator>(const Data& rhs) const;
 bool operator>=(const Data& rhs) const;
 bool operator>(const char* rhs) const;
 bool operator>=(const char* rhs) const;

Returns true iff the argument Data is a prefix (begining) of this Data. For example: assert(Data("abracadabra").prefix("abrac")); 

 bool prefix(const Data& pre) const;

Returns true iff the argument Data is a postfix (end) of this Data. For example: assert(Data("abracadabra").postfix("dabra")); 

 bool postfix(const Data& post) const;

Data::Empty is a static constant that is a Data with no bytes. It is immutable and of length zero.

Data Manipulations

This section is not yet completed 

 Data substr(size_type first, size_type count = Data::npos) const;
 Data operator+(const Data& rhs) const;
 Data operator+(const char* str) const;
 Data operator+(char c) const;
 Data& operator+=(const Data& rhs);
 Data& operator+=(const char* str);
 Data& operator+=(char c);
 Data& operator^=(const Data& rhs);
 Data& append(const char* str, size_type len);
 size_type truncate(size_t len);
 Data trunc(size_type trunc) const;
 void clear();
 int replace(const Data& match, const Data& target);

Data Transformations

This section is not yet completed 

 Data md5() const;
 Data& lowercase();
 Data& uppercase();
 Data hex() const;
 Data escaped() const;
 Data charEncoded() const;
 Data charUnencoded() const;
 Data urlEncoded() const;
 Data urlDecoded() const;
 std::ostream& urlEncode(std::ostream& s)
 std::ostream& urlDecode(std::ostream& s)
 Data base64decode() const;
 Data base64encode(bool useUrlSafe=false) const;

 size_t hash() const;

 size_t caseInsensitivehash() const;

 template<class Predicate> std::ostream&
     escapeToStream(std::ostream& str,
                    Predicate shouldEscape) const;

Data Conversion

Converting from Other Types

This section is not yet finished 

 Data& operator=(const char* str);

Converts from any type T that supports the insertion operator<< to Data. This construct is used chiefly for debugging. Conversions like this can usually be handled more efficiently with direct use of DataStream. 

 class <T>
 static Data from(const T& x);

Converting to Other Types

This section is not yet completed 

 int convertInt() const;

 size_t convertSize() const;

 double convertDouble() const;

 UInt64 convertUInt64() const;

Examining the Data

This section is not yet completed 

 char& operator[](size_type p);
 char operator[](size_type p) const;
 char& at(size_type p);
 bool empty() const { return mSize == 0; }
 size_type size() const { return mSize; } 
 const char* data() const;
 const char* c_str() const;
 const char* begin() const;
 const char* end() const;

 size_type find(const Data& match, size_type start = 0) const;
 size_type find(const char* match, size_type start = 0) const;

Static Convenience Methods

These methods are used by Data to generate hash values for use in hash tables. The methods are publically available to aid the creation of custom hashes on other types with contiguous bytes. There are slightly faster hash functions, but these are quite fast, have provable good distribution properties, and can be varied for security purposes. 

 static size_t rawHash(const char* c, size_t size);
 static size_t rawCaseInsensitiveHash(const char* c, size_t size);
Clone this wiki locally