str Struct Reference

#include <str.h>

Inheritance diagram for str:

---

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 k^th byte in this object's internal data buffer.

Parameters:

k

a starting offset into this object's data buffer

Returns:

a pointer to the k^th 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:

• str.h

---

ISC Cryptographic Development Kit - User's Guide
Questions? E-mail ISC technical support
Copyright© 2002-2006 Information Security Corp. All rights reserved.