blob: 24de528f4f2b9d8b48e93f6a0a6cf330ac0b0d2d [file] [log] [blame]
Jeff Thompson25e89382013-09-11 15:35:19 -07001/**
Jeff Thompson7687dc02013-09-13 11:54:07 -07002 * Copyright (C) 2013 Regents of the University of California.
3 * @author: Jeff Thompson <jefft0@remap.ucla.edu>
Jeff Thompson25e89382013-09-11 15:35:19 -07004 * See COPYING for copyright and distribution information.
5 */
6
7#ifndef NDN_BLOB_HPP
8#define NDN_BLOB_HPP
9
10#include "../common.hpp"
11
12namespace ndn {
13
14/**
Jeff Thompson0e6d1422013-09-12 11:36:37 -070015 * A Blob holds a pointer to an immutable byte array implemented as const std::vector<unsigned char>.
16 * This is like a JavaScript string which is a pointer to an immutable string.
17 * It is OK to pass a pointer to the string because the new owner can't change the bytes
Jeff Thompson675d71a2013-09-12 10:57:37 -070018 * of the string. However, like a JavaScript string, it is possible to change the pointer, and so this does allow
Jeff Thompson0e6d1422013-09-12 11:36:37 -070019 * the copy constructor and assignment to change the pointer. Also remember that the pointer can be null.
20 * (Note that we could have made Blob derive directly from vector<unsigned char> and then explicitly use
21 * a pointer to it like shared_ptr<Blob>, but this does not enforce immutability because we can't declare
22 * Blob as derived from const vector<unsigned char>.)
Jeff Thompson25e89382013-09-11 15:35:19 -070023 */
Jeff Thompson0e6d1422013-09-12 11:36:37 -070024class Blob : public ptr_lib::shared_ptr<const std::vector<unsigned char> > {
Jeff Thompson25e89382013-09-11 15:35:19 -070025public:
26 /**
Jeff Thompson0e6d1422013-09-12 11:36:37 -070027 * Create a new Blob with a null pointer.
28 */
29 Blob()
30 {
31 }
32
33 /**
Jeff Thompson25e89382013-09-11 15:35:19 -070034 * Create a new Blob with an immutable copy of the given array.
35 * @param value A pointer to the byte array which is copied.
36 * @param valueLength The length of value.
37 */
38 Blob(const unsigned char* value, unsigned int valueLength)
Jeff Thompson0e6d1422013-09-12 11:36:37 -070039 : ptr_lib::shared_ptr<const std::vector<unsigned char> >(new std::vector<unsigned char>(value, value + valueLength))
Jeff Thompson25e89382013-09-11 15:35:19 -070040 {
41 }
42
43 /**
44 * Create a new Blob with an immutable copy of the array in the given vector.
Jeff Thompson675d71a2013-09-12 10:57:37 -070045 * If you want to transfer the array without copying, the the vector has to start as a
46 * ptr_lib::shared_ptr<std::vector<unsigned char> > and you can use the Blob constructor with this type.
Jeff Thompson25e89382013-09-11 15:35:19 -070047 * @param value A reference to a vector which is copied.
48 */
49 Blob(const std::vector<unsigned char> &value)
Jeff Thompson0e6d1422013-09-12 11:36:37 -070050 : ptr_lib::shared_ptr<const std::vector<unsigned char> >(new std::vector<unsigned char>(value))
Jeff Thompson25e89382013-09-11 15:35:19 -070051 {
52 }
53
54 /**
55 * Create a new Blob to point to an existing byte array. IMPORTANT: After calling this constructor,
Jeff Thompson0e6d1422013-09-12 11:36:37 -070056 * if you keep a pointer to the array then you must treat the array as immutable and promise not to change it.
Jeff Thompson25e89382013-09-11 15:35:19 -070057 * @param value A pointer to a vector with the byte array. This takes another reference and does not copy the bytes.
58 */
59 Blob(const ptr_lib::shared_ptr<std::vector<unsigned char> > &value)
Jeff Thompson0e6d1422013-09-12 11:36:37 -070060 : ptr_lib::shared_ptr<const std::vector<unsigned char> >(value)
Jeff Thompson25e89382013-09-11 15:35:19 -070061 {
62 }
Jeff Thompsond0be4712013-09-12 15:20:05 -070063 Blob(const ptr_lib::shared_ptr<const std::vector<unsigned char> > &value)
64 : ptr_lib::shared_ptr<const std::vector<unsigned char> >(value)
65 {
66 }
Jeff Thompson25e89382013-09-11 15:35:19 -070067
68 /**
Jeff Thompson25e89382013-09-11 15:35:19 -070069 * Return the length of the immutable byte array.
70 */
71 unsigned int size() const
72 {
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070073 if (*this)
74 return (*this)->size();
75 else
76 return 0;
Jeff Thompson25e89382013-09-11 15:35:19 -070077 }
78
79 /**
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070080 * Return a const pointer to the first byte of the immutable byte array, or 0 if the pointer is null.
Jeff Thompson25e89382013-09-11 15:35:19 -070081 */
Jeff Thompson0e6d1422013-09-12 11:36:37 -070082 const unsigned char* buf() const
Jeff Thompson25e89382013-09-11 15:35:19 -070083 {
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070084 if (*this)
Jeff Thompsonf6d5a622013-09-12 12:21:00 -070085 return &(*this)->front();
Jeff Thompsone5ddbed2013-09-12 12:19:31 -070086 else
87 return 0;
Jeff Thompson25e89382013-09-11 15:35:19 -070088 }
Jeff Thompson25e89382013-09-11 15:35:19 -070089};
90
91}
92
93#endif