and
,
* respectively. Defaults to false (no translation).
*/
nstring html_quote(bool para = false) const;
/**
* The html_unquote method is used to form a normal string given
* text from an HTML paragraph. This means that &DDD; escape
* sequences are replaced by single bytes. Some special characters
* are also replaced, e.g. '<' as <
*
* @note
* unicode values (DDD > 255) are not understood.
*/
nstring html_unquote(void) const;
// ---------- I ------------------------------------------------------
/**
* The identifier method is used to convert all non-C-identifier
* characters in the string to underscores. The intention is to
* create a valid C identifier from the string.
*/
nstring identifier(void) const;
// ---------- J ------------------------------------------------------
// ---------- K ------------------------------------------------------
// ---------- L ------------------------------------------------------
size_t
length(void)
const
{
return ref->str_length;
}
/**
* The len_printable method may be used to determine the "printable
* length" of a string. This means the first maxlen characters, or up
* until the first newline, whichever is least.
*
* @param maxlen
* The longest desired string (0 < maxlen < INT_MAX)
* @returns
* int, suitable for passing to %.*s
*/
int len_printable(int maxlen) const;
bool looks_like_utf8(void) const;
// ---------- M ------------------------------------------------------
// ---------- N ------------------------------------------------------
// ---------- O ------------------------------------------------------
nstring
operator+(const nstring &arg)
const
{
string_ty *tmp = str_catenate(ref, arg.ref);
nstring result(tmp);
str_free(tmp);
return result;
}
nstring &
operator+=(const nstring &arg)
{
if (!arg.empty())
{
string_ty *s = str_catenate(ref, arg.ref);
str_free(ref);
ref = s;
}
return *this;
}
/**
* @brief
* test a boolean
*
* The str_bool function is used to test the value of a string, as if
* it contained a number. If it doesn't contain a number, it is as if
* the strings was "1".
*
* @return
* False if the numeric value in the strings was zero, or the
* empty string. True if the numeric value in the string was
* non-zero, or the string was non-numeric.
*/
operator bool() const;
/**
* The logical netation operator.
* Returns the negation of the bool() operator.
*/
bool operator!() const;
/**
* The equal-to operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool
operator==(const nstring &rhs)
const
{
return (ref == rhs.ref);
}
/**
* The not-equal-to operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool
operator!=(const nstring &rhs)
const
{
return (ref != rhs.ref);
}
/**
* The less-than operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool operator<(const nstring &rhs) const;
/**
* The less-than-or-equal operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool operator<=(const nstring &rhs) const;
/**
* The greater-than operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool operator>(const nstring &rhs) const;
/**
* The greater-than-or-equal operator.
*
* @param rhs
* The right hans side of the comparison.
*/
bool operator>=(const nstring &rhs) const;
/**
* The indexing operator is used to extract the nth character of a
* string. Indexes out of range will result in the NUL character
* being returned.
*
* @param n
* The character to extract. Zero based.
* @returns
* The character requested, or NUL if the index is out
* of range.
*/
char
operator[](size_t n)
const
{
return (n < size() ? ref->str_text[n] : '\0');
}
// ---------- P ------------------------------------------------------
// ---------- Q ------------------------------------------------------
/**
* @brief
* quote C meta-characters
*
* The quote_c method is used to create a new string which
* quotes the C meta-characters in the input string.
*/
nstring quote_c(void) const;
/**
* @brief
* quote shell meta-characters
*
* The quote_shell method is used to create a new string which
* quotes the shell meta-characters in the input string.
*
* @return
* a pointer to a string in dynamic memory. Use str_free()
* when finished with. The contents of the structure pointed
* to shall not be altered.
*/
nstring quote_shell(void) const;
/**
* @brief
* quote Cook meta-characters
*
* The quote_cook method is used to create a new string which
* quotes the Cook meta-characters in the input string.
* If no quoting is required, none will be used.
*/
nstring quote_cook(void) const;
// ---------- R ------------------------------------------------------
/**
* The replace method may be used to alter a string by replacing
* one constant substring with another.
*
* @note
* The replacement is not done in situ. The original
* string is unaltered.
*
* @param lhs
* The substring to look for.
* @param rhs
* The substring to replace @a lhs if found.
* @param maximum
* The maximum number of times to perform the replacement.
* Defaults to "infinity".
* @returns
* A new string with the replacements made.
*/
nstring replace(const nstring &lhs, const nstring &rhs, int maximum = -1)
const;
// ---------- S ------------------------------------------------------
size_t
size(void)
const
{
return ref->str_length;
}
/**
* @brief
* remove excess white space
*
* The snip method is used to remove white space from the beginning
* and end of the string. Interior white space is left unchanged.
*
* @return
* another string
*/
nstring snip(void) const;
/**
* The starts_with method is ised to test whether this string
* starts with the given prefix.
*
* @param prefix
* The string to test for.
*/
bool starts_with(const nstring &prefix) const;
/**
* The substr method may be used to extract a substring from this
* string. (Named for compatibility with std::string.)
*
* @param start
* The offset into the string where the substring starts. If
* negative, is measured from the end.
* @param nbytes
* The number of bytes to extract, if that many available. If
* negative, measured to the left (text not reversed).
* @returns
* a string, note that it could be less than nbytes long.
*/
nstring substr(long start, long nbytes) const;
/**
* Swap the contents of two nsdtring objects. This method swaps
* the internal pointers to string_ty. This can be done safely
* without involving a reference / unreference cycle and is
* therefore highly efficient.
*/
void swap(nstring &rhs);
// ---------- T ------------------------------------------------------
/**
* The to_long method attempts to turn a string into a long value.
* It returns zero on failure. The radix is always 10.
*/
long to_long(void) const;
/**
* @brief
* remove excess white space
*
* The trim method is used to remove white space from the beginning
* and end of the string, and replace all other runs of one or more
* white space characters with a single space.
*
* @return
* another string
*/
nstring trim(void) const;
/**
* The trim_extension method is used to build a new string without
* the file extension. For example, the string "a/b.c" will return
* "a/b".
*/
nstring trim_extension(void) const;
/**
* The trim_first_directory method may be used to trim the
* left-most directory from a path. If there is no slash, the
* string is returned with no change.
*/
nstring trim_first_directory(void) const;
/**
* @brief
* remove excess white space
*
* The trim_lines method is used to remove white space from the
* beginning and end of lines within the string, and replace
* all other runs of one or more white space characters with a
* single space.
*
* @return
* another string
*/
nstring trim_lines(void) const;
/**
* The trim_right method is used to trim while space from the right
* hand side (the end) of the given string.
*/
nstring trim_right(void) const;
/**
* The trim_right_lines method is used to trim while space from the
* right hand side of each line of the given string.
*/
nstring trim_right_lines(void) const;
// ---------- U ------------------------------------------------------
/**
* @brief
* convert to upper case
*
* The str_upcase function is used to create a new string where the
* lower case characters in the input string are converted to upper
* case.
*
* @return
* a pointer to a string in dynamic memory. Use str_free()
* when finished with. The contents of the structure pointed
* to shall not be altered.
*/
nstring upcase(void) const;
/**
* The url_quote mwthod is used to form a string suitable for use
* within an HTML href="" string, or similar. This means that
* special characters and unprintable characters are replaced with
* %NN escape sequences.
*/
nstring url_quote(void) const;
/**
* The url_unquote method is used to form a normal string given an
* HTML href="" string, or similar. This means that %NN escape
* sequences are replaced with single bytes.
*/
nstring url_unquote(void) const;
// ---------- V ------------------------------------------------------
/**
* @brief
* check is valid
*
* The valid mthod is used to confirm that the given string
* pointer, @a str, points to a valid string. Usually used for
* debugging, often in assert()s.
*
* @return
* Non-zero if valid, zero if invalid.
*/
bool valid(void) const;
/**
* assert(valid());
*/
void validate(void) const;
/**
* @brief
* format text
*
* The str_vformat function is used to create a new string by
* interpreting the @a fmt string. All formats understood by the
* ANSI C printf(3) are understood by this function (but probably
* not your favorite proprietary extension). In addition the '%S'
* specifier expects a string_ty * argument.
*
* @param fmt
* The format string to be interpreted when constructing the
* return value.
* @param ap
* Where to obtain additional arguments required by the @a fmt string.
*
* @return
* a pointer to a string in dynamic memory. Use str_free()
* when finished with. The contents of the structure pointed
* to shall not be altered.
*/
static nstring vformat(const char *fmt, va_list ap);
// ---------- W ------------------------------------------------------
// ---------- X ------------------------------------------------------
// ---------- Y ------------------------------------------------------
// ---------- Z ------------------------------------------------------
private:
/**
* The ref instance variable is used to remember the location of
* the object common to all of the references.
* The is never the NULL pointer.
*/
string_ty *ref;
/**
* The get_empty_ref() class method is used to get a
* pointer to an underlying string object of length zero.
*/
static string_ty *get_empty_ref(void);
};
inline nstring
operator+(const char *lhs, const nstring &rhs)
{
return nstring(lhs).catenate(rhs);
}
inline nstring
operator+(const nstring &lhs, const char *rhs)
{
return lhs.catenate(nstring(rhs));
}
// vim: set ts=8 sw=4 et :
#endif // COMMON_NSTRING_H