String Methods

Properties: Scalar

strCat() catenates string scalars together to produce a new string scalar. The subject array and the argument must be string type and of the same shape. Either array can also be a scalar, in which case it is catenated with each item of the other array.

Properties:

charToStr() accepts a character vector as its argument and returns a scalar string as its result. The datatype of the character vector can be either 1-byte (dtByte) or 2-byte (dtChar). strToChar() accepts a string scalar as its argument and returns a character (dtChar) vector. strToByte() accepts a string scalar and returns a vector of bytes, assuming all characters in the string are between 0 and 255; otherwise it throws an SA_CANNOT_CONVERT exception.

Properties:

strToByteMatrix() and strToCharMatrix() convert string vectors into matrices with one row for each string. This is a useful form to hold variable-length character sequences in cases where strings are inefficient. The character or byte matrix arrays can be used for file-mapped arrays, for example, whereas string arrays can not, and they have the added advantage of not filling the SmartArrays string table.

The resulting matrix will have one row for each string and ncols columns. If ncols is -1, the matrix will have as many columns as the length of the longest string. If ncols is less than the length of the longest string, these methods produce an SA_LENGTH exception.

By default the NUL character is used to pad strings to the number of columns in the matrix. You can optionally specify an alternative character to use instead of NUL. The examples below use '.' so the pad characters are visible when displayed.

strToByteMatrix() will throw an SA_CANNOT_CONVERT exception if any 2-byte character in the string cannot be converted to a 1-byte character.

strLen() accepts any array as its argument and returns an integer array of the same shape that contains the length of the string item at each position or -1 if the item is not a string.

strLookup() searches each string in the subject array a, which must be of type dtString, for the string scalar argument b.  The result is an integer array of the same shape as a containing the offset in each string where b is found, or -1 if it is not found.  The optional offsets array is an integer scalar or array with the same shape as a, indicating where the search should begin.  If the offset is negative, the search begins at an offset from the end of each string. In this case, the result still indicates the position of the substring from the start of the string.

strLookup() can be used to perform several common string-search algorithms, such as finding all strings that contain a substring:

Properties: String filter; only string items in the array are affected; others are copied to the result unchanged.

Note: Spaces and tabs are treated as white space characters.

Properties: String filter; only string items in the array are affected; others are copied to the result unchanged.

Note: All Unicode characters for which there are defined upper and lower case forms are handled.

Properties: String filter; only string items in the array are affected; others are copied to the result unchanged.

These methods can be applied to any array. The argument must be a string scalar. strWith() filters strings according to their intersection with the set of characters in the argument, while strWithout() filters with the set difference.

The subject array must be a string scalar. The argument can be a string array of any shape. The result of strFind() is a boolean array whose leading dimensions are the shape of b and whose last dimension is the length of the string scalar. A 1 in the result marks the position where the substring is found, including overlapping substrings. An empty string matches at every position.

The subject array must be a string scalar. The argument represents pairs of strings to locate and their replacements. It can be a 2-item string vector or a 2-column matrix of strings. The result is a string scalar where the first string in each pair is replaced with the second. For multiple strings replacements, the string matches are applied in the order in which they occur in the matrix. Overlapping matches are not replaced.

The subject array must be a string scalar. strToNumber() attempts to convert sequences of non-whitespace characters to numbers. The result is a floating-point vector containing the represented numbers. For non-blank fields that are not well-formed numbers, the result contains a NaN.

The subject array can be a string array of any shape. The argument specifies the location and optional maximum length of the substrings to select from the subject array. It can be an integer scalar or 2-item vector. If different offsets or lengths are to be selected from each string, the argument can be an integer array whose rank is one greater than the rank of the subject array and whose leading dimensions match its shape. The last dimension must be either length 1 or length 2. The result of subStr() is a string array whose shape is the same shape as the subject array.

subStr() selects substrings beginning at an offset specified by the first item of the argument. Positive numbers select offsets from the beginning of each string, and negative numbers select offsets backward from the end of each string. The second item of the argument is optional and specifies the maximum length of the substring to select. If the length indicated exceeds the length of the string, the result string will contain only as many characters as are available in the source string. In other words, subStr never pads its result; if you need padding, you can use strToChar() and takeBy() to add fill characters and guarantee the length of the resulting strings.