str Struct Reference

#include <str.h>

Inheritance diagram for str:

Inheritance graph

Detailed Description

Class str is somewhat similar to the STL std::string type.

str objects created by the supplied constructors have null terminators so that they can be used as normal C strings. (For example, they can be passed to strlen().) The terminating null is not considered part of the str object or counted in its length.

For efficiency, the implementation of str uses shared memory and performs garbage collection. Hence the following caveats:

1. A str object returned by a function might not have a null terminator.

2. Do not directly modify a str object via a pointer to its character buffer unless you are sure that no other str objects share that buffer.

3. The amount of memory allocated to a non-empty str object can exceed the size of the string stored in it, but there is no memory allocated when the length is zero.

Call str::purify() to guarantee a null terminator and an unshared character buffer.

Warnings: str::str(const char *p) may truncate binary data copied from p so be very careful in situations like this:

  char x[10] = "sdf\0asld\n";
  str y = x;      // y only gets "sdf\0" and the rest of x is discarded!

Instead, use:

  str y(10,x);

or

  str y = str(10,x);

Also, the concatenation logic does not preserve null terminators. In other words, be careful about:

  str a("United "), b("States");  // both null terminated
  str c = a + b;                  // a,c possibly not null terminated
  a.purify();                     // a is null terminated again


Recommendations for strict FIPS 140-1 compliance: 

All applications should use str objects for storing keys as the class's
destructor will zeroize the object's memory when it is explicitly 
destroyed or goes out of scope. If the application does not use the CDK's 
str class for storing keys, the application must guarantee that the memory 
used to store keys is zeroized. 

Class str contains no methods that perform or use cryptographic operations.


Public Types

 npos = -1
 = -1 (invalid byte offset or character not found)
enum  { npos = -1 }
 For compatibility with the standard string class. More...

Public Member Functions

Constructors and Destructors
 str ()
 Constructor used to create an empty str object.
 str (const str &x)
 Copy constructor.
 str (int len)
 Constructor used to create an object of a specified length.
 str (int len, const char *p, int max=0)
 Constructor used to create an object with specified data.
 str (const char *p)
 Constructor used to create an object containing an ASCII text string.
 ~str ()
 Destructor, calls clear() to zeroize all data fields.
Inspectors and Manipulators
int length () const
 Get the length in bytes of this object's data.
char * constptr () const
 Get a (const) pointer to the kth byte in this object's internal data buffer.
char * rawptr (int k=0) const
 Get a pointer to the kth byte in this object's internal data buffer.
const char * c_str ()
 Null-terminate this object and get a (const) pointer to its internal data buffer.
void makeunique ()
 Ensure that this object's character buffer is not shared by another object.
void nullterminate ()
 Null-terminate this object.
void purify ()
 Null-terminate this object and ensure that its character buffer is not shared by another str object.
str skip (int k) const
 Create a new object containing all but the leftmost k bytes of this object.
str trunc (int k) const
 Truncate this str object.
bool isText () const
 Predicate used to determine if this object contains printable ASCII text.
String Operators
 operator const char * () const
 Get a pointer to this object's internal data buffer; operator version.
str operator= (const str &x)
 Assignment operator used to duplicate a str object.
bool operator== (const str &y) const
 Operator used to test equality of two str objects.
bool operator!= (const str &y) const
 Operator used to test inequality of two str objects.
int operator+ () const
 Operator used to obtain the length in bytes of this object's data.
int operator[] (int k) const
 Get the k-th byte in this object's data buffer.
char & operator[] (int k)
 Get a reference to the k-th byte in this object's data buffer.
str operator+ (const str &y) const
 Create a new str object by concatenating a specified str object onto this one.
void operator+= (const str &y)
 Concatenate a specified str object onto this one.
void operator^= (const str &y)
 XOR two str object together.
Conversion Functions
str tohex (int withprefix=0) const
 Convert tbis object's data to a string of ASCII hex digits.
str tobase64 (int rfcpad=1) const
 Base64 encode this object.
str tobin64 () const
 Base64 decode this object.
double todouble () const
 Convert to double.
long tolong () const
 Convert to long.
str towrap (int width) const
 Line wrap the data in this object.
Substrings, Search, and Replace
str substr (int offset, int length) const
 Extract a substring from this str object.
int find (char ch, int offset=0) const
 Find the first instance of a specified character in this str object.
str replace (int pos, int n, const str &z)
 Replace substring with string.
str insert (int pos, const str &z)
 Insert substring.
str erase (int pos, int n)
 Erase substring.


Member Enumeration Documentation

anonymous enum

For compatibility with the standard string class.

Enumerator:
npos  = -1 (invalid byte offset or character not found)


Constructor & Destructor Documentation

str ( int  len  )  [inline, explicit]

Constructor used to create an object of a specified length.

Parameters:
len the size of buffer to preallocate in bytes

str ( int  len,
const char *  p,
int  max = 0 
) [inline, explicit]

Constructor used to create an object with specified data.

Parameters:
len the length in bytes of the data buffer
p a pointer to the buffer containing data for the new string
max the length of this object's data buffer (if more than len bytes is desired)

str ( const char *  p  ) 

Constructor used to create an object containing an ASCII text string.

Parameters:
p a pointer to a null-terminated ASCII text string


Member Function Documentation

str erase ( int  pos,
int  n 
) [inline]

Erase substring.

Parameters:
pos starting offset
n number of bytes to erase
Returns:
the modified str object

int find ( char  ch,
int  offset = 0 
) const

Find the first instance of a specified character in this str object.

Parameters:
ch the character to be found
offset a starting point for the search
Returns:
the index of the specified character in the str object or, if the character is not found, npos

str insert ( int  pos,
const str z 
) [inline]

Insert substring.

Parameters:
pos starting offset
z string to be inserted into this object
Returns:
the modified str object

bool isText (  )  const

Predicate used to determine if this object contains printable ASCII text.

Returns:
true, if every character in this object has an ASCII code between 8 and 127
false, otherwise

int length (  )  const [inline]

Get the length in bytes of this object's data.

Returns:
length of this object in bytes

operator const char * (  )  const [inline]

Get a pointer to this object's internal data buffer; operator version.

Returns:
a pointer to (the beginning of) this object's internal data buffer
Remarks:
Use of this member function is dangerous. Remember that a str object's internal data buffer may be shared by other str objects, and that it will be de-allocated when the str object goes out of scope.

bool operator!= ( const str y  )  const [inline]

Operator used to test inequality of two str objects.

Parameters:
y the str object to which this one is to be compared
Returns:
true, if y is not equivalent to this str object
false, otherwise.

str operator+ ( const str y  )  const [inline]

Create a new str object by concatenating a specified str object onto this one.

Parameters:
y the str object to be appended to this one
Returns:
a str object containing the contents of this str followed by the contents of y

int operator+ (  )  const [inline]

Operator used to obtain the length in bytes of this object's data.

Returns:
length of this object's data

str operator= ( const str x  ) 

Assignment operator used to duplicate a str object.

Parameters:
x the str object to assign to this object

Reimplemented in asn.

bool operator== ( const str y  )  const

Operator used to test equality of two str objects.

Parameters:
y the str object to which this one is to be compared
Returns:
true, if y is equivalent to this str object
false, otherwise.

char& operator[] ( int  k  )  [inline]

Get a reference to the k-th byte in this object's data buffer.

Parameters:
k the index of the byte to be dereferenced
Returns:
a reference to the k-th byte in this object's data buffer
Remarks:
This operator facilitates s[1] = 'C' type assignments.

Use of Use of this member function is dangerous. Remember that a str object's internal data buffer may be shared by other str objects.

int operator[] ( int  k  )  const [inline]

Get the k-th byte in this object's data buffer.

Parameters:
k the index of the byte to return
Returns:
the k-th byte in this object's data buffer

void operator^= ( const str y  ) 

XOR two str object together.

Parameters:
y the str to be XOR'ed into this one

char* rawptr ( int  k = 0  )  const [inline]

Get a pointer to the kth byte in this object's internal data buffer.

Parameters:
k a starting offset into this object's data buffer
Returns:
a pointer to the kth byte in this object's internal data buffer
Remarks:
Use of this member function is dangerous. Remember that a str object's internal data buffer may be shared by other str objects.

str replace ( int  pos,
int  n,
const str z 
) [inline]

Replace substring with string.

Parameters:
pos starting offset
n number of characters to replace
z replacement string
Returns:
the modified str object

str skip ( int  k  )  const

Create a new object containing all but the leftmost k bytes of this object.

Parameters:
k the number of bytes to be skipped
Returns:
a str consisting of all but the first k bytes of this object

str substr ( int  offset,
int  length 
) const

Extract a substring from this str object.

Parameters:
offset the starting index of the substring
length the length of the substring to be extracted
Returns:
a str containing a substring of the specified length starting at the specified index

str tobase64 ( int  rfcpad = 1  )  const

Base64 encode this object.

Parameters:
rfcpad padding indicator: use 1 to ensure that the encoded length is a multiple of 4, 0 if you don't care
Returns:
a str containing the base64-encoded data
Remarks:
A padding indicator of 1 results in the output str being printable encoded according to RFC 1113 and RFC 1421

str tobin64 (  )  const

Base64 decode this object.

Returns:
a str containing the (binary) data obtained by base64 decoding this object

double todouble (  )  const [inline]

Convert to double.

Returns:
a double representation of this string

str tohex ( int  withprefix = 0  )  const

Convert tbis object's data to a string of ASCII hex digits.

Parameters:
withprefix prefix indicator: 1 to prepend '0x' to the output string, 0 to omit this prefix
Returns:
a str containing an ASCII hexadecimal representation of the data in this object

long tolong (  )  const

Convert to long.

Returns:
a signed integer from this string, using up to 4 bytes

str towrap ( int  width  )  const

Line wrap the data in this object.

Parameters:
width the desired line length
Returns:
a new str with newlines inserted every 'width' characters

str trunc ( int  k  )  const

Truncate this str object.

Parameters:
k the number of bytes to retain
Returns:
a str containing only the initial k bytes of this object


The documentation for this struct was generated from the following file:
ISC Cryptographic Development Kit - User's Guide
ISC website
Questions? E-mail ISC technical support
Copyright© 2002-2006 Information Security Corp. All rights reserved.