ASL
Public Member Functions | Static Public Member Functions | List of all members
String Class Reference

Detailed Description

String represents a character string that behaves similarly to JavaScript strings in that it can be converted to/from other types easily.

Future versions might allow only explicit conversions but now they are implicit.

Strings are byte-based using UTF-8 (or Local 8-bit if ASL_ANSI is defined). In order to use string literals with non-ASCII characters, source code must be encoded in UTF-8. Indices and substrings operate on code-units.

String firstName = "John", lastName = "Doe";
String name = firstName + " " + lastName; // use += when possible, it's faster
asl::String::String
String()
Constructs an empty string.
Definition: String.h:154

Unicode (UTF-8) case conversions and case-insensitive comparisons are supported.

String babel = "Ñandú εξέλιξη жизни"; // UTF-8 string with Latin, Greek and Cyrilic text
babel.toUpperCase() -> "ÑANDÚ ΕΞΈΛΙΞΗ ЖИЗНИ"
babel.equalsNocase("ñanDÚ εΞΈλΙξΗ ЖиЗНИ") -> true

There are convenience methods for simple transformations:

if( filename.toLowerCase().endsWith(".xml") )
String id = text.trim(); // remove whitespace before and after
if( !email.contains('@') ) {}
Array<String> parts = path.split("/"); // cut a path into its parts

Remember in UTF-8 characters can have different byte-length. Use the length() method to get the number of bytes (i.e. code units) and count() to get the number of code points (i.e. actual characters). To get the individual wide characters you can use the chars() method which returns an array of code points or iterate the string with a foreach loop.

String euros = "3€";
euros.length() // returns 4 (bytes)
euros.count() // returns 2 (characters)
euros.chars() // returns the array [51, 8364] (the codes of '3' and '€')
for(int c : euros)
printf("%i ", c); // prints "51 8364"

A String automatically converts to char* or wchar_t* when needed. When converting to wchar_t* the UTF-8 string will be expanded to wide characters in a temporary buffer. This way you can call functions that require wide characters transparently.

String dirName = "Mis imágenes" // this is UTF-8
CreateDirectoryW( dirName ); // this gets converted to UTF-16 LPCWSTR

There are automatic conversions to/from many basic types, but please use with care!

String number = 14; // int to string
Array<double> a(20);
a[number] = number + ".5"; // -> a[14] = 14.5 string to double
fopen(number + ".txt", "r"); // -> "14.txt" string to const char*
String items = array(1, 2, 3); // -> "[1,2,3]" array of ints to string
asl::array
Array< T > array(const T &a0, const T &a1)
Creates an array with the 2 elements given as arguments (there are overloads from 1 to 6 elements)
Definition: Array.h:755

#include <String.h>

Public Member Functions

 String ()
 Constructs an empty string.
 
 String (int cap, int n)
 Constructs an uninitialized string with internal capacity cap and length n, useful for writing to it externally.
 
 String (const char *txt)
 Constructs a string from a C string (pointer to null-terminated string)
 
 String (const char *txt, int n)
 Constructs a string from the first n characters of a character buffer pointed by txt
 
 String (const Array< char > &txt)
 Constructs a string from a char array.
 
 String (const Array< wchar_t > &txt)
 Constructs a string from an array of wide chars (UTF16)
 
 String (char c)
 Constructs a string from a character.
 
 String (char c, int n)
 Constructs a string consisting of character c repeated n times. More...
 
 String (const String &s)
 Constructs a string from another string object.
 
 String (const wchar_t *s)
 Constructs a string from an Unicode UTF16 string.
 
 String (Long x)
 Constructs a string from a 64bit long integer number.
 
 String (ULong x)
 Constructs a string from a 64bit unsigned long integer number.
 
 String (int x)
 Constructs a string from an integer number.
 
 String (unsigned x)
 Constructs a string from an unsigned integer number.
 
 String (float x)
 Constructs a string from a float floating-point number.
 
 String (double x)
 Constructs a string from a double floating-point number.
 
 String (bool x)
 Constructs a string from a boolean value.
 
 operator int () const
 Converts this string to an integer number.
 
 operator unsigned () const
 Converts this string to an unsigned integer number.
 
 operator float () const
 Converts this string to a 32-bit floating-point number.
 
 operator double () const
 Converts this string to a 64-bit floating-point number.
 
 operator Long () const
 Converts this string to a 64-bit integer number.
 
 operator bool () const
 Returns true if this string is not empty (warning: this might change in the future to mean isTrue(), use ok())
 
template<class T >
T to () const
 Converts this string to another basic type, if supported n = str.to<int>();
 
bool operator! () const
 Returns true if this string is empty (warning: this might change in the future to mean !isTrue(), use !ok())
 
bool ok () const
 Returns true if this string is not empty.
 
 operator const char * () const
 Returns a const pointer to the beginning of the character data (suitable for functions requiring C-style strings)
 
char * data ()
 Returns a pointer to the beginning of the character data (suitable for functions requiring C-style strings)
 
const wchar_t * dataw () const
 Returns a pointer to a Unicode UTF16 representation of this string by expanding from the internal byte representation (suitable for functions requiring C-style wide strings (LPWSTR))
 
 operator const wchar_t * () const
 Returns a const pointer to a Unicode UTF16 representation of this string by expanding from the internal byte representation (suitable for functions requiring C-style wide strings (LPCWSTR))
 
const char * operator* () const
 Returns a const pointer to the beginning of the character data (suitable for functions for functions requiring C-style strings)
 
bool isTrue () const
 Returns true if this string represents a non-false value (e.g. More...
 
String toLocal () const
 Returns a local charset version of this string (which is UTF8 or ANSI)
 
unsigned hexToInt () const
 Converts this string to an unsigned integer number by interpreting it as an hexadecimal number.
 
String & resize (int n, bool keep=true, bool newlen=true)
 Resizes this string to a length of n, keeping or not its original contents.
 
String & fix ()
 Restores the internal state of a String that has been modified externally and changed its length.
 
String & fix (int n)
 Restores the internal state of a String that has been modified externally and changed its length to a known value.
 
Array< int > chars () const
 Returns a list of Unicode characters (code points) in this string.
 
const String & operator| (const String &s) const
 Returns the left string if it is not empty, or the right otherwise.
 
template<class T >
String operator| (const T &s) const
 Returns the left string if it is not empty, or the right otherwise.
 
char & operator[] (int i)
 Returns a reference to the i-th character in this string (byte-based)
 
const char & operator[] (int i) const
 Returns a reference to the i-th character in this string (byte-based)
 
int indexOf (char c, int i0=0) const
 Returns the first index where character c appears in this string, optionally starting search at position i0, or -1 if it is not found.
 
int indexOf (const char *s, int i0=0) const
 Returns the first index where substring s appears in this string, optionally starting search at position i0, or -1 if it is not found.
 
int indexOf (const String &s, int i0=0) const
 Returns the first index where substring s appears in this string, optionally starting search at position i0, or -1 if it is not found.
 
int lastIndexOf (char c) const
 Returns the last index where character c appears in this string, or -1 if it is not found.
 
int lastIndexOf (const char *s) const
 Returns the last index where string s appears in this string, or -1 if it is not found.
 
int length () const
 Returns the length of this string in bytes.
 
int wlength () const
 Returns the length of this string in wchar_t wide chars (UTF16 code units)
 
int count () const
 Returns the number of full characters (code points) in the string.
 
String substring (int i, int j) const
 Return the substring starting at position i and up to but not including position j
 
String substring (int i) const
 Return the substring starting at position i and up to the end.
 
String substr (int i, int n) const
 Return the substring starting at position i with at most n chars, if i is negative it counts from the end.
 
String trimmed () const
 Return a string that is like this but without space at the beginning or end.
 
String & trim ()
 Removes space at the beginning and end of the string.
 
bool startsWith (const String &s) const
 Tests if this string starts with the given substring.
 
bool endsWith (const String &s) const
 Tests if this string ends with the given substring.
 
bool startsWith (char c) const
 Tests if this string starts with the given character.
 
bool endsWith (char c) const
 Tests if this string ends with the given character.
 
bool contains (const char *s) const
 Tests if this string contains the given substring.
 
bool contains (char s) const
 Tests if this string contains the given character.
 
String toLowerCase () const
 Returns a lowercase version of this string.
 
String toUpperCase () const
 Returns an uppercase version of this string.
 
Array< String > split () const
 Returns a list of strings obtained by cutting this string by whitespace. More...
 
Array< String > split (const String &sep) const
 Returns a list of strings obtained by cutting this string by occurences of the separator sep. More...
 
Dic< String > split (const String &sep1, const String &sep2) const
 Parses a string and creates a Dic using sep1 as pair separator (e.g. ','), and sep2 as key/value separator (e.g. '='). More...
 
String replace (const String &a, const String &b) const
 Returns a string like this one but in which occurences of substring a are replaced by b
 
String & replaceme (char a, char b)
 Replaces all occurences of character a with b in place
 

Static Public Member Functions

static String fromCodes (const Array< int > &codes)
 Creates a string from an array of Unicode code points.
 
static String fromCode (int code)
 Creates a one-'character' string from an Unicode code point.
 
static String fromLocal (const String &a)
 Creates a (UTF8 or ANSI) string from a string in the local charset.
 
static String repeat (char c, int n)
 Constructs a string consisting of character c repeated n times.
 
static String f (const char *fmt,...) ASL_PRINTF_W2(1)
 Creates a string by formatting values using printf-style specification fmt.
 

Constructor & Destructor Documentation

◆ String()

String ( char  c,
int  n 
)
explicit

Constructs a string consisting of character c repeated n times.

Deprecated:
Use String::repeat() instead.

Member Function Documentation

◆ isTrue()

bool isTrue ( ) const

Returns true if this string represents a non-false value (e.g.

none of: "", "0", "false", "False", "FALSE", "no", "NO")

◆ split() [1/3]

Array<String> split ( ) const
inline

Returns a list of strings obtained by cutting this string by whitespace.

String(" a \t\n b c ").split() -> ["a", "b", "c"]

◆ split() [2/3]

Array<String> split ( const String &  sep) const
inline

Returns a list of strings obtained by cutting this string by occurences of the separator sep.

String("a,b,c").split(",") -> ["a", "b", "c"]

◆ split() [3/3]

Dic<String> split ( const String &  sep1,
const String &  sep2 
) const

Parses a string and creates a Dic using sep1 as pair separator (e.g. ','), and sep2 as key/value separator (e.g. '=').

String("a:1,b:2,c:3").split(",", ":") -> {"a": "1", "b": "2", "c": "3"}
The documentation for this class was generated from the following file: