blob: 0de0442473b8152946a484ac5dd247d2d8aae5a6 [file] [log] [blame]
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
/*
* Copyright (c) 2013, Regents of the University of California
* Alexander Afanasyev
*
* BSD license, See the LICENSE file for more information
*
* Author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
*/
#ifndef NDN_NAME_COMPONENT_H
#define NDN_NAME_COMPONENT_H
#include "blob.h"
NDN_NAMESPACE_BEGIN
namespace name {
/**
* @ingroup ndn-cxx
* @brief Class to representing binary blob of NDN name component
*
* This class is based on Blob (std::vector<char>) and just provides several helpers
* to work with name components, as well as operator to apply canonical
* ordering on name components
*/
class Component : public Blob
{
public:
/**
* @brief Default constructor an empty exclude
*/
Component ();
/**
* @brief Create component from URI encoded string
* @param uri URI encoded name component (convert escaped with % characters)
*/
Component (const std::string &uri);
/**
* @brief Create component from URI encoded string, with string specified by a pair of iterators
* @param begin begin iterator pointing to the URI encoded name
* @param end end iterator
*/
Component (std::string::const_iterator begin, std::string::const_iterator end);
/**
* @brief Create component using a binary blob
* @param buf pointer to first byte of binary blob to store as a name component
* @param length length of the binary blob
*/
Component (const void *buf, size_t length);
/**
* @brief Apply canonical ordering on component comparison
* @return 0 They compare equal
* <0 If *this comes before other in the canonical ordering
* >0 If *this comes after in the canonical ordering
*
* @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
*/
int
compare (const Component &other) const;
/**
* @brief Apply canonical ordering on component comparison (less or equal)
*
* @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
*/
inline bool
operator <= (const Component &other) const;
/**
* @brief Apply canonical ordering on component comparison (less)
*
* @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
*/
inline bool
operator < (const Component &other) const;
/**
* @brief Apply canonical ordering on component comparison (greater or equal)
*
* @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
*/
inline bool
operator >= (const Component &other) const;
/**
* @brief Apply canonical ordering on component comparison (greater)
*
* @see http://www.ccnx.org/releases/latest/doc/technical/CanonicalOrder.html
*/
inline bool
operator > (const Component &other) const;
////////////////////////////////////
// Component construction helpers //
////////////////////////////////////
/**
* @brief Create component from URI encoded string
* @param uri URI encoded name component (convert escaped with % characters)
* @return *this
*/
Component &
fromUri (const std::string &uri);
/**
* @brief Create component from URI encoded string, with string specified by a pair of iterators
* @param begin begin iterator pointing to the URI encoded name
* @param end end iterator
* @return *this
*/
Component &
fromUri (std::string::const_iterator begin, std::string::const_iterator end);
/**
* @brief Create network-ordered numeric component
*
* @param number number to be encoded and added as a component
* @return *this
*
* Number is encoded and added in network order. Tail zero-bytes are not included.
* For example, if the number is 1, then 1-byte binary blob will be added 0x01.
* If the number is 256, then 2 binary blob will be added: 0x01 0x01
*
* If the number is zero, an empty component will be created
*/
Component &
fromNumber (uint64_t number);
/**
* @brief Create network-ordered numeric component to the name with marker
*
* @param number number to be encoded and added as a component
* @param marker byte marker, specified by the desired naming convention
*
* Currently defined naming conventions of the marker:
* - 0x00 sequence number
* - 0xC1 control number
* - 0xFB block id
* - 0xFD version number
*
* This version is almost exactly as appendNumber, with exception that it adds initial marker.
* The number is formatted in the exactly the same way.
*
* @see fromNumber
*/
Component &
fromNumberWithMarker (uint64_t number, unsigned char marker);
//////////////////////////////////////////////////////////////////////////////////
// helpers
//////////////////////////////////////////////////////////////////////////////////
/**
* @brief Convert binary blob name component to std::string (no conversion is made)
* @param comp name component to be converted
* @see asUriString
*/
std::string
toBlob () const;
/**
* @brief Write blob of the name component to the specified output stream
* @param os output stream
*/
void
toBlob (std::ostream &os) const;
/**
* @brief Convert binary blob name component to std::string, escaping all non-printable characters in URI format
* @param comp name component to be converted
* @see asString
*/
std::string
toUri () const;
/**
* @brief Write name as URI to the specified output stream
* @param os output stream
*/
void
toUri (std::ostream &os) const;
/**
* @brief Convert binary blob name component (network-ordered number) to number
* @param comp name component to be converted
*/
uint64_t
toNumber () const;
/**
* @brief Convert binary blob name component (network-ordered number) to number, using appropriate marker from the naming convention
* @param comp name component to be converted
* @param marker required marker from the naming convention
*
* If the required marker does not exist, an exception will be thrown
*/
uint64_t
toNumberWithMarker (unsigned char marker) const;
/**
* @brief Convert binary blob name component, assuming sequence number naming convention (marker = 0x00)
* @param comp name component to be converted
* @see asNumberWithMarker
*/
inline uint64_t
toSeqNum () const;
/**
* @brief Convert binary blob name component, assuming control number naming convention (marker = 0xC1)
* @param comp name component to be converted
* @see asNumberWithMarker
*/
inline uint64_t
toControlNum () const;
/**
* @brief Convert binary blob name component, assuming block ID naming convention (marker = 0xFB)
* @param comp name component to be converted
* @see asNumberWithMarker
*/
inline uint64_t
toBlkId () const;
/**
* @brief Convert binary blob name component, assuming time-stamping version naming convention (marker = 0xFD)
* @param comp name component to be converted
* @see asNumberWithMarker
*/
inline uint64_t
toVersion () const;
};
bool
Component::operator <= (const Component &other) const
{
return (compare (other) <= 0);
}
bool
Component::operator < (const Component &other) const
{
return (compare (other) < 0);
}
bool
Component::operator >= (const Component &other) const
{
return (compare (other) >= 0);
}
bool
Component::operator > (const Component &other) const
{
return (compare (other) > 0);
}
inline uint64_t
Component::toSeqNum () const
{
return toNumberWithMarker (0x00);
}
inline uint64_t
Component::toControlNum () const
{
return toNumberWithMarker (0xC1);
}
inline uint64_t
Component::toBlkId () const
{
return toNumberWithMarker (0xFB);
}
inline uint64_t
Component::toVersion () const
{
return toNumberWithMarker (0xFD);
}
/**
* @brief Stream output operator (output in escaped URI format)
*/
inline std::ostream&
operator <<(std::ostream &os, const Component &name)
{
name.toUri (os);
return os;
}
} // name
NDN_NAMESPACE_END
#endif // NDN_NAME_COMPONENT_H