NEXUS CLASS LIBRARY: NxsString Class

NEXUS CLASS LIBRARY | home | classes | functions

# Class NxsString

## Friends

operator <<

## Exceptions

NxsX_NotANumber

## Enums

CmpEnum

## Member Functions

Abbreviates, AddQuotes, AddTail, BlanksToUnderscores, BreakPipeSeparatedList, Capitalize, clear, ConvertToDouble, ConvertToInt, ConvertToLong, ConvertToUnsigned, endl, Equals, EqualsCaseInsensitive, GetQuoted, GetVecOfPossibleAbbrevMatches, IsADouble, IsALong, IsCapAbbreviation, IsInVector, IsNexusPunctuation, IsStdAbbreviation, NumberThenWord, NxsString, NxsString, NxsString, operator+=, operator+=, operator+=, operator+=, operator+=, operator+=, operator+=, operator+=, operator<<, operator<<, operator<<, operator<<, operator<<, operator<<, operator<<, operator<<, operator<<, operator<<, operator=, operator=, PrintF, p_str, QuotesNeeded, RightJustifyDbl, RightJustifyLong, RightJustifyString, SetToShortestAbbreviation, ShortenTo, ToHex, ToLower, ToUpper, UnderscoresToBlanks, UpperCasePrefix

## Class Description

A string class for use with the Nexus Class Library. NxsString inherits most of its functionality from the standard template library class string, adding certain abilities needed for use in NCL, such as the ability to discern whether a short string represents an abbreviation for the string currently stored. Another important addition is the member function PrintF, which accepts a format string and an arbitrary number of arguments, allowing a string to be built in a manner similar to the standard C function printf. Many operators are also provided for appending numbers to the ends of strings, an ability which is very useful for producing default labels (e.g. taxon1, taxon2, etc.).

### Key to symbols and colors

public, protected, private, `A` = abstract, `C` = constructor, `D` = destructor, `I` = inline, `S` = static, `V` = virtual, `F` = friend

Enums

`enum CmpEnum` |
| `respect_case = 0`
| `no_respect_case = 1`
| `abbrev = 2`

Member Functions

I |  | `bool` |  | `Abbreviates``(const NxsString &s, NxsString::CmpEnum mode)`
|  |  |  | Returns true if the stored string is an abbreviation (or complete copy) of the supplied string s.
|  | `NxsString` |  | `&AddQuotes``()`
|  |  |  | Replaces the stored string with a copy of itself surrounded by single quotes (single quotes inside the string are converted to the '' pair of characters that signify a single quote). Returns a reference to itself.
|  | `NxsString` |  | `&AddTail``(char c, unsigned n)`
|  |  |  | Adds n copies of the character c to the end of the stored string and returns a reference to itself.
|  | `NxsString` |  | `&BlanksToUnderscores``()`
|  |  |  | Converts any blank spaces found in the stored string to the underscore character.
F |  | `NxsStringVector` |  | `BreakPipeSeparatedList``(const NxsString &strList)`
|  |  |  | Written to make it easy to initialize a vector of strings. Similar to the perl split function. Converts a string like this -- "A|bro|ken strin|g" -- to a vector of strings with four elements: "A", "bro", "ken string", and "g".
I |  | `NxsString` |  | `&Capitalize``()`
|  |  |  | Capitalizes all lower case letters in the stored string by calling ToUpper.
I |  | `void` |  | `clear``()`
|  |  |  | Most containers in the standard template library can be completely erased using the clear function, but none is provided for the class string and hence is provided here.
|  | `double` |  | `ConvertToDouble``()`
|  |  |  | Converts the stored string to a double using the standard C function strtod, throwing NxsX_NotANumber if the conversion fails. Returns DBL_MAX or -DBL_MAX if the number is out of bounds.
|  | `int` |  | `ConvertToInt``()`
|  |  |  | Converts the stored string to an int using the standard C function strtol, throwing NxsX_NotANumber if the conversion fails. Returns INT_MAX if the number is too large to fit in an int or -INT_MAX if it is too small.
|  | `long` |  | `ConvertToLong``()`
|  |  |  | Converts the stored string to a long using the standard C function strtol, throwing NxsX_NotANumber if the conversion fails.
|  | `unsigned` |  | `ConvertToUnsigned``()`
|  |  |  | Converts the stored string to an unsigned int using the standard C function strtol, throwing NxsX_NotANumber if the conversion fails. Returns UINT_MAX if the number is too large to fit in an unsigned (or was a negative number).
IF |  | `NxsString` |  | `&endl``(NxsString &s)`
|  |  |  | Appends a newline character to the string s and the returns a reference to s. Used with << operator to allow strings to be written to like ostreams.
I |  | `bool` |  | `Equals``(const NxsString &s, NxsString::CmpEnum mode)`
|  |  |  | Uses the mode argument to call (and return the result of) the correct string comparison function.
|  | `bool` |  | `EqualsCaseInsensitive``(const NxsString &s)`
|  |  |  | Returns true if the stored string is a non-case-sensitive copy of the argument s. Note: will return true if both the stored string and s are empty strings.
I |  | `NxsString` |  | `GetQuoted``()`
|  |  |  | Returns a single-quoted version of the NxsString. The calling object is not altered. Written for ease of use. Simply copies the stored string, then returns the copy after calling its AddQuotes function.
F |  | `NxsStringVector` |  | `GetVecOfPossibleAbbrevMatches``(const NxsString &testStr, const NxsStringVector &possMatches)`
|  |  |  | Returns a vector of NxsString objects that match the entire testStr.
|  | `bool` |  | `IsADouble``()`
|  |  |  | Returns true if the stored string can be interpreted as a double value, and returns false otherwise.
|  | `bool` |  | `IsALong``()`
|  |  |  | Returns true if stored string can be interpreted as a long integer.
|  | `bool` |  | `IsCapAbbreviation``(const NxsString &s)`
|  |  |  | Returns true if the stored string is a case-insensitive abbreviation (or complete copy) of s and the stored string has all of the characters that are in the initial capitalized portion of s. For example if s is "KAPpa" then "kappa", "kapp", or "kap" (with any capitalization pattern) will return true and all other strings will return false. Always returns false if the stored string has length of zero.
I |  | `bool` |  | `IsInVector``(const NxsStringVector &s, NxsString::CmpEnum mode)`
|  |  |  | Returns true if the Equals comparison function is true for this or any element in the vector s.
I |  | `bool` |  | `IsNexusPunctuation``(const char c)`
  |  |  |  | Returns true if c is any Nexus punctuation character:
       ()[]{}/,;:=*'"`-+<>
|  | `bool` |  | `IsStdAbbreviation``(const NxsString &s, bool respectCase)`
|  |  |  | Returns true if the string is a abbreviation (or complete copy) of the argument s.
I |  | `NxsString` |  | `&NumberThenWord``(unsigned i, const NxsString s)`
|  |  |  | Creates a new string (and returns a reference to the new string) composed of the integer i followed by a space and then the string s. If i is not 1, then an 's' character is appended to make s plural. For example, if i were 0, 1, or 2, and s is "character", then the returned string would be "0 characters", "1 character" or "2 characters", respectively. Obviously this only works if adding an 's' to the supplied string makes it plural.
CI |  | `` |  | `NxsString``()`
|  |  |  | The default constructor.
CI |  | `` |  | `NxsString``(const char *s)`
|  |  |  | A copy constructor taking a C-string argument.
CI |  | `` |  | `NxsString``(const NxsString &s)`
|  |  |  | A copy constructor taking a NxsString reference argument.
|  | `NxsString` |  | `&operator+=``(const double d)`
|  |  |  | Appends a string representation of the supplied double to the stored string and returns a reference to itself.
I |  | `NxsString` |  | `&operator+=``(const char *s)`
|  |  |  | Appends the supplied C-string s to the stored string.
I |  | `NxsString` |  | `&operator+=``(const NxsString &s)`
|  |  |  | Appends the characters in the supplied NxsString reference s to the stored string.
I |  | `NxsString` |  | `&operator+=``(const char c)`
|  |  |  | Appends the character c to the stored string.
I |  | `NxsString` |  | `&operator+=``(const int i)`
|  |  |  | Uses the standard C sprintf function to append the character representation of the supplied integer i' to the stored string (format code %d). For example, if the stored string is "taxon" and i is 9, the result is "taxon9".
I |  | `NxsString` |  | `&operator+=``(unsigned i)`
|  |  |  | Uses standard C function sprintf to append the unsigned integer i to the stored string (format code %u).
I |  | `NxsString` |  | `&operator+=``(const long l)`
|  |  |  | Uses standard C function sprintf to append the long integer l to the stored string (format code %ld).
I |  | `NxsString` |  | `&operator+=``(const unsigned lon)`
|  |  |  | Uses standard C function sprintf to append the unsigned long integer l to the stored string (format code %lu).
I |  | `NxsString` |  | `&operator<<``(NxsString &(*funcPtr)(NxsStrin)`
|  |  |  | Allows functions that take and return references to NxsString strings to be placed in a series of << operators. See the NxsString endl function.
I |  | `NxsString` |  | `&operator<<``(int i)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(unsigned i)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(long l)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(unsigned lon)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(double d)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(const char *c)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(char c)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
I |  | `NxsString` |  | `&operator<<``(const NxsString &s)`
|  |  |  | Another way to call the += operator (written to make it possible to use a NxsString like an ostream)
IF |  | `ostream` |  | `&operator<<``(ostream &out, const NxsString &s)`
|  |  |  | Writes the string s to the ostream out.
I |  | `NxsString` |  | `&operator=``(const char *s)`
|  |  |  | Sets the stored string equal to the supplied C-string s.
I |  | `NxsString` |  | `&operator=``(char c)`
|  |  |  | Sets the stored string to the supplied character 'c'.
|  | `int` |  | `PrintF``(const char *formatStr, ...)`
  |  |  |  | Appends a printf-style formatted string onto the end of this NxsString and returns the number of characters added to the string. For example, the following code would result in the string s being set to "ts-tv rate ratio = 4.56789":
       double kappa = 4.56789;
       NxsString s;
       s.PrintF("ts-tv rate ratio = %.5f", kappa);
I |  | `unsigned` |  | `*p_str``(unsigned cha)`
|  |  |  | Returns string as a Pascal string (array of unsigned characters with the length in the first byte).
|  | `bool` |  | `QuotesNeeded``()`
|  |  |  | Returns true if the string needs to be surrounded by single-quotes to make it a single nexus token.
|  | `NxsString` |  | `&RightJustifyDbl``(double x, unsigned w, unsigned p, bool clear_first)`
|  |  |  | Right-justifies x in a field w characters wide with precision p, using blank spaces to fill in unused portions on the left-hand side of the field. Specify true for clear_first to first empty the string. Assumes that the specified width is enough to accommodate the string representation of x.
|  | `NxsString` |  | `&RightJustifyLong``(long x, unsigned in, bool clear_first)`
|  |  |  | Right-justifies x in a field w characters wide, using blank spaces to fill in unused portions on the left-hand side of the field. Specify true for clear_first to first empty the string. Assumes w is large enough to accommodate the string representation of x.
|  | `NxsString` |  | `&RightJustifyString``(const NxsString &s, unsigned w, bool clear_first)`
|  |  |  | Right-justifies s in a field w characters wide, using blank spaces to fill in unused portions on the left-hand side of the field. Specify true for clear_first to first empty the string. Assumes that the specified width is enough to accommodate s.
F |  | `bool` |  | `SetToShortestAbbreviation``(NxsStringVector &strVec, bool allowTooShort)`
|  |  |  | Transforms the vector of NxsString objects by making them all lower case and then capitalizing the first portion of them so that the capitalized portion is enough to uniquely specify each. Returns true if the strings are long enough to uniquely specify each. Horrendously bad algorithm, but shouldn't be called often.
|  | `NxsString` |  | `&ShortenTo``(unsigned n)`
|  |  |  | Shortens stored string to n - 3 characters, making the last three characters "...". If string is already less than n characters in length, this function has no effect. This is useful when it is desirable to show some of the contents of a string, even when the string will not fit in its entirety into the space available for displaying it. Assumes that n is at least 4.
S |  | `NxsString` |  | `ToHex``(long p, unsigned nFours)`
|  |  |  | Creates a string representation of the hexadecimal version of the long integer p. For example, if p equals 123, and if 2 was specified for nFours, the resulting string would be "7B". If 4 was specified for nFours, then the resulting string would be "007B".
|  | `NxsString` |  | `&ToLower``()`
|  |  |  | Converts every character in the stored string to its lower case equivalent.
|  | `NxsString` |  | `&ToUpper``()`
|  |  |  | Capitalizes every character in the stored string.
|  | `NxsString` |  | `&UnderscoresToBlanks``()`
|  |  |  | Converts any underscore characters found in the stored string to blank spaces.
|  | `NxsString` |  | `UpperCasePrefix``()`
|  |  |  | Checks to see if the stored string begins with upper case letters and, if so, returns all of the contiguous capitalized prefix. If the stored string begins with lower case letters, an empty string is returned.