SalString
Namespace: PPJ.Runtime
Assembly: PPJ.Runtime.50 (5.0.0.0)
Represents a SAL string or binary buffer, with SAL null semantics and implicit conversions to and from String.
- C#
- VB.NET
public class SalString : IComparable, IConvertible, IFormattable, INullable, ISalType, IXmlSerializable
Public Class SalString
Inherits IComparable
Implements IConvertible, IFormattable, INullable, ISalType, IXmlSerializable
A null value is a SalString instance whose IsNull property is true; it is distinct from a null object reference. Both null and empty values satisfy IsEmpty.
Text constructors retain the entire string. Byte-array constructors store one byte per character and set Length to the first zero byte. Use Value for the full character buffer and GetBlob for its bytes; ToString returns only the text portion of a blob.
String operations generally return a result without changing this instance. Overloads with a reference parameter replace the caller's variable. IsBlob is writable, so instances, including the shared null and empty values, should not be treated as immutable.
Example:
using PPJ.Runtime;
SalString name = " Ada Lovelace ";
SalString displayName = name.Trim();
string text = displayName; // "Ada Lovelace"
SalString firstName = displayName.Left(3); // "Ada"
SalString missing = (string)null;
bool isMissing = missing.IsNull; // true
string missingText = missing; // string.Empty
SalString data = new SalString(new byte[] { 65, 0, 66 });
string prefix = data.ToString(); // "A"
byte[] bytes = data.GetBlob(); // { 65, 0, 66 }
Constructors
SalString()
Initializes a new instance containing a non-null empty text string.
SalString(x)
Initializes a new instance with the specified text.
| Name | Type | Description |
|---|---|---|
| x | String | The text to wrap, or for a SAL null value. |
Embedded zero characters are retained and included in Length.
SalString(chars)
Initializes a new text instance from a character array.
| Name | Type | Description |
|---|---|---|
| chars | Char[] | The characters to copy, or for an empty string. |
SalString(chars, index, length)
Initializes a new text instance from a range of characters.
| Name | Type | Description |
|---|---|---|
| chars | Char[] | The array containing the characters to copy. |
| index | Int32 | The zero-based index of the first character. |
| length | Int32 | The number of characters to copy. |
Throws:
- ArgumentNullException chars is null.
- ArgumentOutOfRangeException The index or length is negative, or the range extends beyond the array.
SalString(blob)
Initializes a new binary instance from the supplied bytes.
| Name | Type | Description |
|---|---|---|
| blob | Byte[] | The bytes to copy, or for a SAL null blob. |
Each byte is stored as one character. Length stops at the first zero byte; GetBlob preserves the full buffer.
SalString(blob, index, length)
Initializes a binary buffer using the specified source and buffer indices.
| Name | Type | Description |
|---|---|---|
| blob | Byte[] | The source bytes, or for a SAL null blob. |
| index | Int32 | The zero-based source and destination index at which copying starts. |
| length | Int32 | The destination buffer length and exclusive upper source index. |
This overload copies indices from index through length minus one into the same positions in a buffer of length characters. Positions before index remain zero. The length is not a count of bytes starting at the index.
Fields
| Name | Type | Description | Value |
|---|---|---|---|
| Empty | SalString | Represents a shared, non-null empty text value. | |
| Null | SalString | Represents a shared SAL null text value. | |
| NullBlob | SalString | Represents a shared SAL null binary value. |
Properties
IsBlob
Boolean: Gets or sets whether this instance is treated as a binary buffer.
Changing this flag does not convert the buffer or recalculate Length.
IsEmpty
Boolean: Gets whether the full wrapped buffer is null or empty.
A nonempty buffer beginning with a zero character is not empty, even if Length is zero.
IsNull
Boolean: Gets whether the wrapped value is null.
Item(index)
Char: Gets a character from the full underlying buffer.
The index addresses Value, including any characters beyond Length. Throws:
- NullReferenceException The wrapped value is null.
- IndexOutOfRangeException The index is outside the underlying string.
Length
SalNumber: Gets the recorded character length.
For a byte-array value, the length stops at the first zero byte. For ordinary text it includes embedded zero characters. Padding added by SetBufferLength is excluded.
Value
String: Gets the full underlying character buffer.
Methods
Clone()
Creates a separate instance with the same buffer, recorded length, and blob flag.
Returns: SalString. A new instance containing the same value and metadata.
Compare(x, y)
Compares two SAL values using ordinal, case-sensitive text ordering.
| Parameter | Type | Description |
|---|---|---|
| x | SalString | The left value, or . |
| y | SalString | The right value, or . |
Returns: Int32. A negative value if the left value precedes the right value, zero if they compare equal, or a positive value if it follows the right value.
A null object reference sorts before any instance. Non-null instances are compared through their string conversions, so SAL null and empty text values compare equal; blob text ends at its recorded Length.
CompareTo(obj)
Compares this value with a SAL string or a .NET string.
| Parameter | Type | Description |
|---|---|---|
| obj | Object | The value to compare with this instance, or . |
Returns: Int32. A negative value, zero, or a positive value when this instance precedes, equals, or follows the argument.
SAL operands use Compare. Other operands are passed to the wrapped string's culture-sensitive comparison. A SAL null instance compares equal to a null argument and precedes any non-null argument. Throws:
- ArgumentException The wrapped value is non-null and the argument is neither a string, a SalString, nor null.
CompareTo(x)
Compares this instance with another SAL value using ordinal text ordering.
| Parameter | Type | Description |
|---|---|---|
| x | SalString | The value to compare with this instance, or . |
Returns: Int32. A negative value, zero, or a positive value when this instance precedes, equals, or follows the argument.
Uses Compare.
Compress()
Compresses the UTF-8 representation of the full wrapped string using the SAL compression format.
Returns: SalString. A blob containing the compressed bytes and SAL compression header.
Use Uncompress to restore the text. Throws:
- ArgumentNullException The wrapped string is null.
Compress(sRet)
Compresses the UTF-8 representation of the full wrapped string using the SAL compression format.
| Parameter | Type | Description |
|---|---|---|
sRet  | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: Boolean. True after the compressed value has been assigned.
Use Uncompress to restore the text. Throws:
- ArgumentNullException The wrapped string is null.
Concat(x, y)
Concatenates two SAL string values.
| Parameter | Type | Description |
|---|---|---|
| x | SalString | The left value. Must not be a null object reference. |
| y | SalString | The right value. Must not be a null object reference. |
Returns: SalString. The other operand when either operand is null-valued or empty; otherwise, a new text instance containing both full buffers.
When both operands are null-valued or empty, the right operand is returned. A newly constructed result is not marked as a blob.
FirstChar(target, charCode)
Consumes the first character or simulated terminator from the supplied value.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | The value to consume. Replaced with the remainder, or a null blob after the simulated terminator. |
| charCode | SalNumber | Receives the UTF-16 character code, or zero for the simulated terminator. Unchanged if no character is available. |
Returns: Boolean. True when a character or simulated terminator was consumed; false when the buffer size was zero.
Uses Lop. The target must not be a null object reference.
FreeHandle(handle)
Releases one reference acquired for a string handle.
| Parameter | Type | Description |
|---|---|---|
| handle | IntPtr | The handle to release. A zero handle is ignored. |
The registry entry is removed when its reference count reaches zero. Throws:
- InvalidOperationException The nonzero handle is not registered, including a handle whose references have already been released.
FromHandle(handle, free)
Retrieves the string registered for a handle.
| Parameter | Type | Description |
|---|---|---|
| handle | IntPtr | The handle returned by ToHandle. |
free  | Boolean | True to release one acquired reference after retrieving the value; false to keep it. |
Returns: SalString. The registered instance, or Null if the handle is zero or is no longer registered.
FromHandleOnce(handle)
Retrieves a registered string and releases one reference to its handle.
| Parameter | Type | Description |
|---|---|---|
| handle | IntPtr | The handle returned by ToHandle. |
Returns: SalString. The registered instance, or Null for a zero or unregistered handle.
Example:
using PPJ.Runtime;
SalString message = "Ready";
System.IntPtr handle = message.ToHandle(); // Acquire one reference.
SalString restored = SalString.FromHandleOnce(handle); // "Ready"
// The acquired reference has been released; do not call FreeHandle for it again.
FromHex(hex)
Decodes hexadecimal byte pairs into a binary SAL value.
| Parameter | Type | Description |
|---|---|---|
| hex | String | The hexadecimal byte pairs, optionally preceded by the lowercase prefix 0x. |
Returns: SalString. The decoded blob, or NullBlob when the input is null or shorter than two characters.
Use an even number of hexadecimal digits. Letter digits may be uppercase or lowercase. The method does not validate that every character is a hexadecimal digit. Throws:
- InvalidOperationException The input contains an incomplete byte pair.
GetBlob()
Copies the low byte of every character in the full buffer.
Returns: Byte[]. A new byte array, or an empty array for a null or empty value.
Includes data after zero characters and any buffer padding. This method does not perform a text-encoding conversion.
GetBufferLength()
Returns the full buffer size, including the simulated terminator for text values.
Returns: SalNumber. The underlying string length for a blob, or that length plus one for text. A null blob has size zero; a null text value has size one.
IsValidCurrency(precision, scale)
Determines whether the string can be parsed as a currency value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses currency parsing rules and validates digit grouping.
IsValidCurrency(precision, scale, provider)
Determines whether the string can be parsed as a currency value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses currency parsing rules and validates digit grouping.
IsValidCurrency(precision, scale, format, provider)
Determines whether the string can be parsed as a currency value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses currency parsing rules and validates digit grouping.
IsValidDateTime()
Determines whether the string can be parsed as a date/time value.
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses ToDate, including its fallback parsing rules.
IsValidDateTime(provider)
Determines whether the string can be parsed as a date/time value.
| Parameter | Type | Description |
|---|---|---|
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses ToDate, including its fallback parsing rules.
IsValidDateTime(format, provider)
Determines whether the string can be parsed as a date/time value.
| Parameter | Type | Description |
|---|---|---|
| format | String | The preferred date/time format, or or an empty string to use default parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses ToDate, including its fallback parsing rules.
IsValidDecimal(precision, scale)
Determines whether the string can be parsed as a decimal value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
IsValidDecimal(precision, scale, provider)
Determines whether the string can be parsed as a decimal value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
IsValidDecimal(precision, scale, format, provider)
Determines whether the string can be parsed as a decimal value within the specified precision and scale.
| Parameter | Type | Description |
|---|---|---|
| precision | Int32 | The total permitted decimal precision. The absolute value must be less than 10 raised to precision minus scale. |
| scale | Int32 | The maximum permitted number of fractional decimal places. |
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
IsValidIdentifierName()
Determines whether the string follows the SAL identifier character rules.
Returns: Boolean. True if the first character is a letter or underscore and subsequent characters are letters, digits, or underscores; otherwise, false.
Uses Unicode letter and digit classification. Null and empty values are invalid. This method does not check reserved words.
IsValidInteger()
Determines whether the string can be parsed as a number with no fractional part.
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing rather than a fixed-width integer range. Currency and exponent notation are accepted if the result has no fractional part.
IsValidInteger(format)
Determines whether the string can be parsed as a number with no fractional part.
| Parameter | Type | Description |
|---|---|---|
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing rather than a fixed-width integer range. Currency and exponent notation are accepted if the result has no fractional part.
IsValidNumber()
Determines whether the string can be parsed as a decimal number.
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
IsValidNumber(provider)
Determines whether the string can be parsed as a decimal number.
| Parameter | Type | Description |
|---|---|---|
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
IsValidNumber(format, provider)
Determines whether the string can be parsed as a decimal number.
| Parameter | Type | Description |
|---|---|---|
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: Boolean. True if parsing and validation succeed; false for null, empty, or invalid input.
Uses decimal parsing with currency and exponent notation and validates digit grouping.
Left(length)
Returns the leading characters of the string.
| Parameter | Type | Description |
|---|---|---|
| length | Int32 | The requested character count, clamped to zero through Length. |
Returns: SalString. The requested prefix, or an empty string for a null or empty value.
Left(length, target)
Returns the leading characters of the string. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| length | Int32 | The requested character count, clamped to zero through Length. |
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Lop(target)
Returns the first character code and assigns the remaining full buffer to the target.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | Receives the string without its first character, or a null blob when consuming the simulated terminator. Unchanged if the buffer size is zero. |
Returns: SalNumber. The first UTF-16 character code; zero for the simulated terminator of an empty text value; or -1 when the buffer size is zero.
Mid(pos, length)
Returns a substring within the recorded string length.
| Parameter | Type | Description |
|---|---|---|
| pos | Int32 | The zero-based starting position, clamped to zero through Length. |
| length | Int32 | The requested character count. Negative values become zero; values beyond the end are shortened. |
Returns: SalString. The requested substring, or an empty string when no characters are selected.
Mid(pos, length, target)
Returns a substring within the recorded string length. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| pos | Int32 | The zero-based starting position, clamped to zero through Length. |
| length | Int32 | The requested character count. Negative values become zero; values beyond the end are shortened. |
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Repeat(times)
Concatenates the full buffer with itself the specified number of times.
| Parameter | Type | Description |
|---|---|---|
| times | Int32 | The repetition count. Values less than one produce an empty string. |
Returns: SalString. The repeated string, or an empty string for a null value or zero recorded length.
Repeat(times, target)
Concatenates the full buffer with itself the specified number of times. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| times | Int32 | The repetition count. Values less than one produce an empty string. |
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Replace(startPos, length, replace)
Replaces a range of characters with the specified text.
| Parameter | Type | Description |
|---|---|---|
| startPos | Int32 | The zero-based starting position, clamped to zero through Length. |
| length | Int32 | The number of characters to remove, clamped to the available recorded length. |
| replace | String | The replacement text, or to remove the selected range. |
Returns: SalString. The resulting text, or an empty string if this value is SAL null.
A zero removal length inserts text. A position at or beyond Length inserts at that position after clamping.
Replace(startPos, length, replace, target)
Replaces a range of characters with the specified text. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| startPos | Int32 | The zero-based starting position, clamped to zero through Length. |
| length | Int32 | The number of characters to remove, clamped to the available recorded length. |
| replace | String | The replacement text, or to remove the selected range. |
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
A zero removal length inserts text. A position at or beyond Length inserts at that position after clamping.
Right(length)
Returns the trailing characters within the recorded string length.
| Parameter | Type | Description |
|---|---|---|
| length | Int32 | The requested character count, clamped to zero through Length. |
Returns: SalString. The requested suffix, or an empty string for a null or empty value.
Right(length, target)
Returns the trailing characters within the recorded string length. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| length | Int32 | The requested character count, clamped to zero through Length. |
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Scan(pattern)
Searches the string using SAL wildcard matching.
| Parameter | Type | Description |
|---|---|---|
| pattern | String | The search pattern. Use % for a sequence, _ for one character, and a backslash to escape the next character. |
Returns: SalNumber. The zero-based match offset, or -1 when no match is found. Returns zero when both the value and pattern are null or empty.
Matching ignores case using current-culture character casing.
SetBufferLength(length)
Produces a string with the requested underlying buffer length.
| Parameter | Type | Description |
|---|---|---|
| length | Int32 | The requested buffer length. Zero or negative values produce an empty string. |
Returns: SalString. The original instance if the buffer already has the requested positive length; otherwise, the resized text value.
Shorter buffers are truncated. Longer buffers are padded with zero characters while Length records the original full buffer length. Newly created results are text values, not blobs.
SetBufferLength(target, length)
Produces a string with the requested underlying buffer length.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
| length | Int32 | The requested buffer length. Zero or negative values produce an empty string. |
Returns: Boolean. True after the result has been assigned.
Shorter buffers are truncated. Longer buffers are padded with zero characters while Length records the original full buffer length. Newly created results are text values, not blobs.
ToDate()
Parses the string as a date/time value.
Returns: SalDateTime. The parsed value, or Null for null, empty, or unparseable input.
Parsing tries the supplied format when present, then general date parsing, built-in SAL formats, and the default SAL long format. The format is a preference, not a strict validation mask. SAL S and L select short and long dates; hhhh, AMPM, and mmmmmm map to 24-hour hours, a designator, and fractional seconds.
ToDate(format)
Parses the string as a date/time value.
| Parameter | Type | Description |
|---|---|---|
| format | String | The preferred date/time format, including supported SAL placeholders, or or an empty string for default parsing. |
Returns: SalDateTime. The parsed value, or Null for null, empty, or unparseable input.
Parsing tries the supplied format when present, then general date parsing, built-in SAL formats, and the default SAL long format. The format is a preference, not a strict validation mask. SAL S and L select short and long dates; hhhh, AMPM, and mmmmmm map to 24-hour hours, a designator, and fractional seconds.
ToDate(format, provider)
Parses the string as a date/time value.
| Parameter | Type | Description |
|---|---|---|
| format | String | The preferred date/time format, including supported SAL placeholders, or or an empty string for default parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: SalDateTime. The parsed value, or Null for null, empty, or unparseable input.
Parsing tries the supplied format when present, then general date parsing, built-in SAL formats, and the default SAL long format. The format is a preference, not a strict validation mask. SAL S and L select short and long dates; hhhh, AMPM, and mmmmmm map to 24-hour hours, a designator, and fractional seconds.
ToHandle()
Acquires a reference-counted handle for this string value.
Returns: IntPtr. A handle registered for the full string value, or Zero for a SAL null value.
Equal underlying strings share a handle. Each call for a non-null value acquires a reference that must be released by FreeHandle or FromHandleOnce. The handle is a registry identifier, not a native memory address.
Example:
using PPJ.Runtime;
SalString message = "Ready";
System.IntPtr handle = message.ToHandle();
try
{
SalString restored = SalString.FromHandle(handle);
}
finally
{
SalString.FreeHandle(handle);
}
ToHex()
Encodes the full buffer as uppercase hexadecimal byte pairs.
Returns: String. Two hexadecimal digits per byte, without a prefix, or an empty string for a null or empty buffer.
Uses GetBlob, so only the low eight bits of each character are encoded.
Tokenize(startDel, endDel)
Splits the full string into tokens using sets of delimiter characters.
| Parameter | Type | Description |
|---|---|---|
| startDel | String | Characters to skip before each token. Use an empty string to skip none. |
| endDel | String | Characters that end a token. Use an empty string to read to the end. |
Returns: SalArray<SalString>. A new array of tokens, or an empty array for a null or empty value.
Delimiters are sets of individual characters, not multi-character markers. Empty tokens can be produced. Delimiter arguments must not be null for nonempty input.
Example:
using PPJ.Runtime;
SalString text = "Ada,,Grace;Linus";
SalArray<SalString> fields = text.Tokenize("", ",;");
// fields: "Ada", "", "Grace", "Linus".
SalArray<SalString> names = text.Tokenize(",;", ",;");
// names: "Ada", "Grace", "Linus".
// Both ',' and ';' are individual delimiters, not a two-character separator.
Tokenize(startDel, endDel, target)
Splits the full string into tokens using sets of delimiter characters.
| Parameter | Type | Description |
|---|---|---|
| startDel | String | Characters to skip before each token. Use an empty string to skip none. |
| endDel | String | Characters that end a token. Use an empty string to read to the end. |
| target | SalArray<SalString> | The array that receives tokens starting at its lower bounds. Existing elements beyond the copied tokens are retained. |
Returns: SalNumber. The number of tokens copied.
Delimiters are sets of individual characters, not multi-character markers. Empty tokens can be produced. Delimiter arguments must not be null for nonempty input. If tokens are found, the target is made dynamic; if none are found, it is left unchanged.
Example:
using PPJ.Runtime;
SalArray<SalString> target = new SalArray<SalString>();
target.Add("old first");
target.Add("old second");
target.Add("retained");
SalString text = "Ada,Grace";
SalNumber copied = text.Tokenize("", ",", target); // 2
// target now contains "Ada", "Grace", "retained".
// Use the returned count when processing just the newly copied tokens.
ToLower()
Converts the full string to lowercase using the current culture.
Returns: SalString. The lowercase text, or an empty string for a null or empty value.
ToLower(target)
Converts the full string to lowercase using the current culture. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
ToNumber()
Parses the string as a decimal number.
Returns: SalNumber. The parsed value, or Zero for null, empty, or unparseable input.
Supports currency symbols, exponents, parentheses for negative values, and validated digit grouping. Formatted parsing, when requested, is followed by unformatted parsing.
Example:
using PPJ.Runtime;
SalString input = "not a number";
SalNumber fallback = input.ToNumber(); // Zero
SalNumber nullable = input.ToNumber(null); // SalNumber.Null
ToNumber(format)
Parses the string as a decimal number.
| Parameter | Type | Description |
|---|---|---|
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
Returns: SalNumber. The parsed value, or Null for null, empty, or unparseable input.
Supports currency symbols, exponents, parentheses for negative values, and validated digit grouping. Formatted parsing, when requested, is followed by unformatted parsing.
ToNumber(format, provider)
Parses the string as a decimal number.
| Parameter | Type | Description |
|---|---|---|
| format | String | The numeric format used to remove formatting text before parsing, or or an empty string for unformatted parsing. |
| provider | IFormatProvider | The culture-specific formatting information, or to use the default parsing culture. |
Returns: SalNumber. The parsed value, or Null for null, empty, or unparseable input.
Supports currency symbols, exponents, parentheses for negative values, and validated digit grouping. Formatted parsing, when requested, is followed by unformatted parsing.
ToProper()
Uppercases the first character and each character following whitespace, and lowercases other characters.
Returns: SalString. The converted text within Length, or an empty string for a null or empty value.
Uses the current culture. Punctuation does not start a new word.
ToProper(target)
Uppercases the first character and each character following whitespace, and lowercases other characters. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Uses the current culture. Punctuation does not start a new word.
ToUpper()
Converts the full string to uppercase using the current culture.
Returns: SalString. The uppercase text, or an empty string for a null or empty value.
ToUpper(target)
Converts the full string to uppercase using the current culture. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Trim()
Removes leading and trailing whitespace and collapses internal whitespace runs to a single space.
Returns: SalString. The normalized text, or an empty string for a null or empty value.
Carriage returns, line feeds, and nonbreaking spaces are preserved.
Trim(target)
Removes leading and trailing whitespace and collapses internal whitespace runs to a single space. Assigns the result to the target.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | When this method returns, contains the resulting string. The previous value is replaced. |
Returns: SalNumber. The number of characters in the resulting string.
Carriage returns, line feeds, and nonbreaking spaces are preserved.
Uncompress()
Decompresses a buffer in the SAL compression format.
Returns: SalString. The decompressed text, or an empty string for empty input, a short header, or an unrecognized header.
Restores text compressed by Compress. An empty result is not distinguished from rejected input.
Uncompress(target)
Decompresses a buffer in the SAL compression format.
| Parameter | Type | Description |
|---|---|---|
| target | SalString | Receives the decompressed text when the result is nonempty; otherwise, retains its previous value. |
Returns: Boolean. True if a nonempty result was assigned; false if decompression returned an empty string.
Restores text compressed by Compress. An empty result is not distinguished from rejected input. A successfully decompressed empty string also returns false.
Inherited By
| Name | Description |
|---|---|
| SalStringContext | Carries a SAL context object together with its string representation. |
Implements
| Name | Description |
|---|---|
| ISalType | Exposes a SAL value in the form used for database parameter binding. |