DEC C++
Using DEC C++ for DIGITAL UNIX Systems

6.5.2 The basic_string Nonmember Functions

operator+

The following operator+ functions return the string constructed from adding the character or characters in lhs to the character or characters in rhs:

template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+(const charT lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator+( const basic_string<charT, traits, Allocator>& lhs, const charT rhs);

Relational Operators

The following operator:=,= functions return a value of TRUE if lhs :=,= rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> bool operator==( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> bool operator==(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> bool operator==( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The following operator!= functions return a value of TRUE if lhs != rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> bool operator!=( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> bool operator!=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> bool operator!=( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The following operator< functions return a value of TRUE if lhs < rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The following operator> functions return a value of TRUE if lhs > rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The following operator<= functions return a value of TRUE if lhs <= rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<=( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator<=( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The following operator>= functions return a value of TRUE if lhs >= rhs, where lhs and rhs are converted into strings if necessary; otherwise, the following return a value of FALSE:

template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>=( const basic_string<charT, traits, Allocator>& lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>=(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs); template <class charT, class traits, class Allocator> basic_string<charT, traits, Allocator> operator>=( const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);

The swap Function

The following swaps the contents (that is, the data members) of lhs and rhs:

template <class charT, class traits, class Allocator> void swap(basic_string<charT, traits, Allocator>& lhs, basic_string<charT, traits, Allocator>& rhs);

Inserters and Extractors

The following extracts characters from stream is into str until either end-of-file occurs on is or whitespace is encountered in is; any leading whitespace is skipped and str is erased before the extraction:

template <class charT, class traits, class Allocator> istream& operator>>(istream& is, basic_string<charT,traits,Allocator>& str);

The following writes str into the output stream os:

template <class charT, class traits, class Allocator> ostream& operator<<(ostream& os, const basic_string<charT,traits,Allocator> & str);

The following extracts up until the delim (or end-of-file) into the is; it does not skip leading whitespace and str is erased before the extraction:

template <class charT, class traits, class Allocator> istream& getline(istream& is, basic_string<charT,traits,Allocator>& str, charT delim = '\n');

6.5.3 The basic_string typedefs

The following typedefs are provided in the basic_string class:

traits
Is the type used to represent the character traits class used in the string. The traits class provides character primitives such as assignment, comparison, find(), length(), copy(), move(), and assign().
value_type
Is the type of the charT elements in the string, for example char or wchar_t.
allocator_type
Is the type of the allocator. The default is allocator<void>.
size_type
Is the type used to represent the index into the string. The default is size_t.
difference_type
Is the type used to represent the result of arithmetic operations on the iterators. The default is ptrdiff_t.
reference

const_reference
Is the type used to represent a reference (or const reference) of value_type.
pointer

const_pointer
Is the type used to represent a pointer (or const pointer) to value_type.
iterator

const_iterator
Is the type used to iterate over elements of the string.
reverse_iterator

const_reverse_iterator
Is the type used to iterate over elements of the string. This typedef differs from iterator in that ++ will move backward through the string and -- will move forward through the string.

6.5.4 Upgrading from Nonstandard DEC C++ String Package Code

The DEC C++ basic_string Library is designed to replace the nonstandard DEC C++ String Package.

The following list guides you through upgrading nonstandard code to use the new basic_string Library.

Change #include <string.h> or #include <string.hxx> to #include <string>.
Change all declarations of String to string (uppercase S to lowercase s).
The String Package allowed assignment of a string directly to a char*; however, the basic_string Library does not allow this. You can assign the string's const char* representation using the c_str() or data() basic_string member functions. For example:
string s("abc"); char* cp = s; // not allowed const char* cp = s.data(); // ok
The state of the string is undefined if the result of data() is cast to a non-const char* and then the value of that char* is changed.

The String Package member functions upper() and lower() are not in the basic_string Library. You can write these functions as nonmember functions, as follows:

template <class charT, class traits, class Allocator> inline basic_string<charT, traits, Allocator> upper(const basic_string<charT,traits, Allocator>& str) { basic_string<charT, traits, Allocator> newstr(str); for (size_t index = 0; index < str.length(); index++) if (islower(str[index])) newstr[index] = toupper(str[index]); return newstr; } template <class charT, class traits, class Allocator> inline basic_string<charT, traits, Allocator> lower(const basic_string<charT,traits, Allocator>& str) { basic_string<charT, traits, Allocator> newstr(str); for (size_t index = 0; index < str.length(); index++) if (isupper(str[index])) newstr[index] = tolower(str[index]); return newstr; }

Then instead of calling upper() and lower() as member functions of the basic_string, pass the string as an argument. For example:

s2 = s1.upper(); // does not compile s2 = upper(s1); // ok

The String Package match() member function does not exist. Equivalent functionality exists in the STL algorithm mismatch(), although using it is more complicated. For example:

string s1("abcdef"); string s2("abcdgf"); assert(s1.match(s2)==4); // does not compile pair<string::iterator,string::iterator> p(0,0); // ok p=mismatch(s1.begin(),s1.end(),s2.begin()); assert(p.first-s1.begin()==4); string s3 = s1; p=mismatch(s1.begin(),s1.end(),s3.begin()); assert(p.first == s1.end()); // everything matched

The String Package index() member function does not exist. The basic_string Library equivalent is find().
The String Package constructor that takes two positional parameters (a start and end position) and constructs a new string does not exist. It is replaced in the basic_string Library with the member function substr(). For example:
string s("abcde"); string s2 = s1(1,3); // does not compile string s2 = s1.substr(1,3); // ok
Many previously undetected run-time errors now throw standard exceptions in the String Library.

6.5.5 Differences Between the basic_string Library and the Guide string Class

This section describes differences between the DEC C++ basic_string Library and the string class described in the STL Tutorial and Reference Guide (the Guide string class). The Guide string class was included with the original STL implementation provided by the Hewlett-Packard Company.

The major difference between the basic_string Library and the Guide string class is that the basic_string Library can be treated directly as an STL container. The Guide string class can be used as an STL container only if you explicitly apply the conversion operator to vector<char>. For example:

// string class in the Guide #include <bstring.h> #include <vector.h> main() { vector<char> v = string("Hello"); // call an STL algorithm sort(v.begin(),v.end()); for (vector<char>::iterator iter = v.begin(); iter!= v.end(); iter++) cout << (*iter) ; cout << endl; } // equivalent code using the basic_string Library #include <string> main() { string s("Hello"); // call an STL algorithm sort(s.begin(),s.end()); for (string::iterator iter = s.begin(); iter!= s.end(); iter++) cout << (*iter) ; cout << endl; }

A minor difference is that the basic_string Library uses the header file <string> not <bstring.h>. Also, the header file <bstring.h> automatically included <vector>, whereas <string> does not.

The basic_string Library is also fully functional; that is, it supports the functions size(), at(), and swap(), plus those member functions that take STL iterators as arguments.

6.6 Numeric Limits Class

The Numeric Limits class represents information about arithmetic types. For each arithmetic type, the class provides a combination of the information that can be found in the following:

limits.h
float.h
LIA-1 (ISO/IEC 10967-1 Information technology---Language independent arithmetic---Part 1: Integer and floating point arithmetic)
IEEE Standard for Binary Floating-Point Arithmetic

Not all of the information provided by the class members is meaningful for all types. Any value that is not meaningful for a type is set to 0 or false.

6.6.1 The numeric_limits Template Class

A synopsis of the numeric_limits class follows.

template<class T> class numeric_limits { public: static const bool is_specialized = false; inline static T min() throw(); inline static T max() throw(); static const int digits = 0; static const int digits10 = 0; static const bool is_signed = false; static const bool is_integer = false; static const bool is_exact = false; static const int radix = 0; inline static T epsilon() throw(); inline static T round_error() throw(); static const int min_exponent = 0; static const int min_exponent10 = 0; static const int max_exponent = 0; static const int max_exponent10 = 0; static const bool has_infinity = false; static const bool has_quiet_NaN = false; static const bool has_signaling_NaN = false; static const bool has_denorm = false; static const bool has_denorm_loss = false; inline static T infinity() throw(); inline static T quiet_NaN() throw(); inline static T signaling_NaN() throw(); inline static T denorm_min() throw(); static const bool is_iec559 = false; static const bool is_bounded = false; static const bool is_modulo = false; static const bool traps = false; static const bool tinyness_before = false; static const float_round_style round_style = round_toward_zero; };

Specializations are provided for the following types:

numeric_limits<char> numeric_limits<signed char> numeric_limits<unsigned char> numeric_limits<short> numeric_limits<int> numeric_limits<long> numeric_limits<unsigned short> numeric_limits<unsigned int> numeric_limits<unsigned long> numeric_limits<float> numeric_limits<double> numeric_limits<long double>

Note that the ANSI C++ September 1996 draft includes specializations for the bool and wchar_t types as follows:

numeric_limits<bool> numeric_limits<wchar_t>

However, due to lack of support for these types in the current DEC C++ compiler, specializations for them are not provided in the library.

6.6.2 Numeric Limits Class Member Functions

static T min() throw();
This function returns the minimum finite value. Its return value is equivalent to CHAR_MIN, SHRT_MIN, FLT_MIN, DBL_MIN, and so forth. For floating types with denormalization, the function returns the minimum positive normalized value. This function is meaningful for specializations where is_bounded is not equal to false, or where is_bounded and is_signed are both equal to false.
static T max() throw();
This function returns the maximum finite value. Its return value is equivalent to CHAR_MAX, SHRT_MAX, FLT_MAX, DBL_MAX, and so forth. The function is meaningful for all specializations in which is_bounded is not equal to false.
static T epsilon() throw();
This function returns machine epsilon. Its return value is equivalent to FLT_EPSILON, DBL_EPSILON, or LDBL_EPSILON. The function is meaningful for all floating point types.
static T round_error() throw();
This function returns the maximum rounding error.
static T infinity() throw();
This function returns the representation of positive infinity if it is available. The function is meaningful for all specializations for which has_infinity is true. It is required by specializations for which is_iec559 is true.
static T quiet_NaN() throw();
This function returns the representation of a quiet Not a Number if it is available. The function is meaningful for all specializations where has_quiet_NaN is not false. It is is required in specializations where is_iec559 is true.
static T signaling_NaN() throw();
This function returns the representation of a signaling Not a Number if it is available. The function is meaningful for all specializations where has_signaling_NaN is not false. It is required in specializations for which is_iec550 is true.
static T denorm_min() throw();
This function returns the minimum positive denormalized value. It is meaningful for all floating point types. It is required in specializations for which has_denorm is false.

6.6.3 Numeric Limits Class Data Members

const bool is_specialized;
Used to distinguish between types that have specializations and types that do not. If a specialization exists is_specialized is true, otherwise it is false.
const int digits;
This data member indicates the number of radix digits that can be represented. For integer types this is the number of nonsign bits in the representation. For floating point types this is the number of radix digits in the mantissa and is equivalent to FLT_MANT_DIG, DBL_MANT_DIG, or LDBL_MANT_DIG.
const int digits10;
This data member indicates the number of base 10 digits that can be represented without change. It applies to all specializations where is_bounded is true. For floating point types digits10 is equivalent to FLT_DIG, DBL_DIG, or LDBL_DIG.
const bool is_signed;
This data member indicates whether a type is signed or not. It applies to all specializations.
const bool is_integer;
This data member indicates whether a type is an integer or not. It applies to all specializations.
const bool is_exact;
This data member is true if a type has an exact representation. All integer types are exact. It applies to all specializations.
const int radix;
For floating types this data member specifies the base or radix of the exponent and is equivalent to FLT_RADIX. For integer types it specifies the base of the representation.
const int min_exponent;
This data member indicates the minimum negative integer such that radix raised to the power of one less than that integer is a normalized floating point number. It applies to all floating types and is equivalent to FLT_MIN_EXP, DBL_MIN_EXP, or LDBL_MIN_EXP.
const int min_exponent10;
This data member indicates the minimum negative integer such that 10 raised to that power is in the range of normalized floating point numbers. It applies to all floating types and is equivalent to FLT_MIN_10_EXP, DBL_MIN_10_EXP, or LDBL_MIN_10_EXP.
const int max_exponent;
This data member indicates the maximum positive integer such that radix raised to the power one less than that integer is a representable finite floating point number. It applies to all floating types and is equivalent to FLT_MAX_EXP, DBL_MAX_EXP, or LDBL_MAX_EXP.
const int max_exponent10;
This data member indicates the maximum positive integer such that 10 raised to that power is in the range of representable finite floating point numbers. It applies to all floating types and is equivalent to FLT_MAX_10_EXP, DBL_MAX_10_EXP, or LDBL_MAX_10_EXP.
const bool has_infinity;
This data member is true if the type has a representation for positive infinity. It applies to all floating types.
const bool has_quiet_NaN;
This data member is true if the type has a quiet (that is, nonsignaling) Not a Number. It applies to all floating types.
const bool has_signaling_NaN;
This data member is true if the type supports a signaling Not a Number. It applies to all floating types.
const bool has_denorm;
This data member is true for types that support denormalized values. It applies to all floating types.
const bool has_denorm_loss;
This data member is true if loss of accuracy is detected as a denormalization loss, rather than as an inexact result.
const bool is_iec559;
This data member is true if the type adheres to the International Electrotechnical Commission (IEC) 559 standard. It applies to all floating types.
const bool is_bounded;
This data member is true if the set of values represented by the type is finite. All built-in types are bounded. It applies to all specializations.
const bool is_modulo;
This data member is true if a type is modulo. A type is modulo if you can add two positive numbers and have a result that wraps around to a number that is less than the two operands. This data member is usually false for floating types, true for unsigned integers and true for signed integers on most machines. It applies to all specializations.
const bool traps;
This data member is true if the type supports trapping. It applies to all specializations.
const bool tinyness_before;
This data member is true if tinyness is detected before rounding. It applies to all floating types.
const float_round_style round_style;
This data member indicates the rounding style for the type. It applies to all floating types. Specializations for integer types return round_toward_zero. See Section 6.6.4 for possible values.

Contents

Index

DEC C++Using DEC C++ for DIGITAL UNIX Systems

6.5.2 The basic_string Nonmember Functions

6.5.3 The basic_string typedefs

traits

value_type

allocator_type

size_type

difference_type

reference

const_reference

pointer

const_pointer

iterator

const_iterator

reverse_iterator

const_reverse_iterator

6.5.4 Upgrading from Nonstandard DEC C++ String Package Code

6.5.5 Differences Between the basic_string Library and the Guide string Class

6.6 Numeric Limits Class

6.6.1 The numeric_limits Template Class

6.6.2 Numeric Limits Class Member Functions

static T min() throw();

static T max() throw();

static T epsilon() throw();

static T round_error() throw();

static T infinity() throw();

static T quiet_NaN() throw();

static T signaling_NaN() throw();

static T denorm_min() throw();

6.6.3 Numeric Limits Class Data Members

const bool is_specialized;

const int digits;

const int digits10;

const bool is_signed;

const bool is_integer;

const bool is_exact;

const int radix;

const int min_exponent;

const int min_exponent10;

const int max_exponent;

const int max_exponent10;

const bool has_infinity;

const bool has_quiet_NaN;

const bool has_signaling_NaN;

const bool has_denorm;

const bool has_denorm_loss;

const bool is_iec559;

const bool is_bounded;

const bool is_modulo;

const bool traps;

const bool tinyness_before;

const float_round_style round_style;

DEC C++
Using DEC C++ for DIGITAL UNIX Systems