Cadenza : Cadenza Namespace

Overview

Signature

Remarks

Members

Member Details

StringCoda Class

Extension methods for string.

public static class StringCoda

⊟ Remarks

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Members

See Also: Inherited members from object.

⊟ Public Methods

static
CaptureNamedGroups (this string, string) : System.Linq.ILookup<string, string>
Create a System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.
static
CaptureNamedGroups (this string, string, System.Text.RegularExpressions.RegexOptions) : System.Linq.ILookup<string, string>
Create a System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.
static
Captures (this string, string) : IEnumerable<string>
Create a IEnumerable<string> containing all captured values within self that match the regular expression regex.
static
Captures (this string, string, System.Text.RegularExpressions.RegexOptions) : IEnumerable<string>
Create a IEnumerable<string> containing all captured values within self that match the regular expression regex.
static
IsNullOrWhitespace (this string) : bool
Indicates whether self is a null or contains only whitespace.
static
Lines (this string) : IEnumerable<string>
Creates an IEnumerable<string> which will return all lines of text from self.
static
Matches (this string, string) : IEnumerable<System.Text.RegularExpressions.Match>
Create a IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.
static
Matches (this string, string, System.Text.RegularExpressions.RegexOptions) : IEnumerable<System.Text.RegularExpressions.Match>
Create a IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.
static
MatchValues (this string, string) : IEnumerable<string>
Create a IEnumerable<string> containing all text within self that matches regex.
static
MatchValues (this string, string, System.Text.RegularExpressions.RegexOptions) : IEnumerable<string>
Create a IEnumerable<string> containing all text within self that matches regex.
static
Remove (this string, params string[]) : string
Deletes all strings within targets from self.
static
Slice (this string, int, int) : string
Creates a new string of self using indexes of the start and end position.
static
ToEnum<TEnum> (this string) : TEnum
Converts a string into an enumeration value of type TEnum.
static
Tokens (this string, params Func<Nullable<System.Char>,System.Char,System.Boolean>[]) : IEnumerable<string>
Creates an IEnumerable<string> which will return all tokens from self.
static
Words (this string) : IEnumerable<string>
Creates an IEnumerable<string> which will return all words from self.
static
WrappedLines (this string, IEnumerable<int>) : IEnumerable<string>
Splits a string into line segments with a maximum length constrained by widths.
static
WrappedLines (this string, params int[]) : IEnumerable<string>
Splits a string into line segments with a maximum length constrained by widths.

⊟ Member Details

⊟ CaptureNamedGroups Method

Create a System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.

public static System.Linq.ILookup<string, string> CaptureNamedGroups (this string self, string regex)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.

⊟ Returns

A System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null

⊟ Remarks

C# Example 
Assert.AreEqual ("flag=--; name=foo; value=bar",
		"--foo=bar"
		.CaptureNamedGroups (@"^(?<flag>--|-|/)(?<name>[^:=]+)((?<sep>[:=])(?<value>.*))?$")
		.With (r => "flag=" + r ["flag"].Implode () + 
			"; name=" + r ["name"].Implode () +
			"; value=" + r ["value"].Implode ()));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ CaptureNamedGroups Method

Create a System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.

public static System.Linq.ILookup<string, string> CaptureNamedGroups (this string self, string regex, System.Text.RegularExpressions.RegexOptions options)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.
options
A System.Text.RegularExpressions.RegexOptions containing options to control the regular expression.

⊟ Returns

A System.Linq.ILookup<string, string> containing all named groups within regex and the associated captured values within self.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null
ArgumentOutOfRangeException options contains an invalid flag.

⊟ Remarks

C# Example 
Assert.AreEqual ("flag=--; name=foo; value=bar",
		"--foo=bar"
		.CaptureNamedGroups (@"^(?<flag>--|-|/)(?<name>[^:=]+)((?<sep>[:=])(?<value>.*))?$")
		.With (r => "flag=" + r ["flag"].Implode () + 
			"; name=" + r ["name"].Implode () +
			"; value=" + r ["value"].Implode ()));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Captures Method

Create a IEnumerable<string> containing all captured values within self that match the regular expression regex.

public static IEnumerable<string> Captures (this string self, string regex)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.

⊟ Returns

A IEnumerable<string> containing all captured values within self that match the regular expression regex.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null

⊟ Remarks

C# Example 
Assert.IsTrue (
		new[]{"a", "b", "c", "d"}.SequenceEqual (
			"a - b - c - d".Captures (@"(\w+)")));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Captures Method

Create a IEnumerable<string> containing all captured values within self that match the regular expression regex.

public static IEnumerable<string> Captures (this string self, string regex, System.Text.RegularExpressions.RegexOptions options)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.
options
A System.Text.RegularExpressions.RegexOptions containing options to control the regular expression.

⊟ Returns

A IEnumerable<string> containing all captured values within self that match the regular expression regex.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null
ArgumentOutOfRangeException options contains an invalid flag.

⊟ Remarks

C# Example 
Assert.IsTrue (
		new[]{"a", "b", "c", "d"}.SequenceEqual (
			"a - b - c - d".Captures (@"(\w+)")));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ IsNullOrWhitespace Method

Indicates whether self is a null or contains only whitespace.

public static bool IsNullOrWhitespace (this string self)

⊟ See Also

string.Trim

⊟ Parameters

self
A string to check to see if it is null or contains only whitespace characters.

⊟ Returns

true if self is null or contains only whitespace; otherwise, false.

⊟ Remarks

C# Example 
string s = null;
Assert.IsTrue (s.IsNullOrWhitespace());
Assert.IsTrue ("".IsNullOrWhitespace());
Assert.IsTrue ("    ".IsNullOrWhitespace());
Assert.IsFalse ("foo".IsNullOrWhitespace());

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Lines Method

Creates an IEnumerable<string> which will return all lines of text from self.

public static IEnumerable<string> Lines (this string self)

⊟ See Also

TextReaderCoda.Lines(System.IO.TextReader)

⊟ Parameters

self
A string to read lines from.

⊟ Returns

An IEnumerable<string> which will return all lines of text from self.

⊟ Exceptions

Type Reason
ArgumentNullException self is null.

⊟ Remarks

This method is implemented by using deferred execution.

Note: A "line of text" is the same as that used by TextReaderCoda.Lines(System.IO.TextReader).
C# Example 
Assert.IsTrue (new[]{"one", "two", "three"}
		.SequenceEqual ("one\ntwo\nthree".Lines ()));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Matches Method

Create a IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.

public static IEnumerable<System.Text.RegularExpressions.Match> Matches (this string self, string regex)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.

⊟ Returns

A IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null

⊟ Remarks

C# Example 
string match = @"a - b
c - d
e - f";

Match[] matches = match.Matches (@"\w+ - \w+").ToArray();
Assert.AreEqual (3, matches.Length);
Assert.AreEqual ("a - b", matches [0].Value);
Assert.AreEqual ("c - d", matches [1].Value);
Assert.AreEqual ("e - f", matches [2].Value);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Matches Method

Create a IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.

public static IEnumerable<System.Text.RegularExpressions.Match> Matches (this string self, string regex, System.Text.RegularExpressions.RegexOptions options)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.
options
A System.Text.RegularExpressions.RegexOptions containing options to control the regular expression.

⊟ Returns

A IEnumerable<System.Text.RegularExpressions.Match> containing all System.Text.RegularExpressions.Matched text within self.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null
ArgumentOutOfRangeException options contains an invalid flag.

⊟ Remarks

C# Example 
string match = @"a - b
c - d
e - f";

Match[] matches = match.Matches (@"\w+ - \w+").ToArray();
Assert.AreEqual (3, matches.Length);
Assert.AreEqual ("a - b", matches [0].Value);
Assert.AreEqual ("c - d", matches [1].Value);
Assert.AreEqual ("e - f", matches [2].Value);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ MatchValues Method

Create a IEnumerable<string> containing all text within self that matches regex.

public static IEnumerable<string> MatchValues (this string self, string regex)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.

⊟ Returns

A IEnumerable<string> containing all text within self that matches regex.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null

⊟ Remarks

This differs from StringCoda.Captures(string, string) in that no captures (parenthesis) are required within regex.

C# Example 
string match = @"a - b
c - d
e - f";

string[] expected = {"a - b", "c - d", "e - f"};
string[] actual = match.MatchValues(@"\w+ - \w+").ToArray();

AssertAreSame (expected, actual);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ MatchValues Method

Create a IEnumerable<string> containing all text within self that matches regex.

public static IEnumerable<string> MatchValues (this string self, string regex, System.Text.RegularExpressions.RegexOptions options)

⊟ Parameters

self
A string to apply a regular expression to.
regex
A string containing the regular expression to match self against.
options
A System.Text.RegularExpressions.RegexOptions containing options to control the regular expression.

⊟ Returns

A IEnumerable<string> containing all text within self that matches regex.

⊟ Exceptions

Type Reason
ArgumentException Regular expression parsing error.
ArgumentNullException

self is null

-or-

regex is null
ArgumentOutOfRangeException options contains an invalid flag.

⊟ Remarks

This differs from StringCoda.Captures(string, string) in that no captures (parenthesis) are required within regex.

C# Example 
string match = @"a - b
c - d
e - f";

string[] expected = {"a - b", "c - d", "e - f"};
string[] actual = match.MatchValues(@"\w+ - \w+").ToArray();

AssertAreSame (expected, actual);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Remove Method

Deletes all strings within targets from self.

public static string Remove (this string self, params string[] targets)

⊟ Parameters

self
A string to remove all occurrences of all elements within targets.
targets
A string array containing the strings to remove from self .

⊟ Returns

A string instance in which all strings within targets have been removed.

⊟ Exceptions

Type Reason
ArgumentNullException self or targets is null.

⊟ Remarks

C# Example 
Assert.AreEqual (" Bar ", "Foo Bar Monkeys".Remove ("Foo", "Monkeys"));
Assert.AreEqual (" Bar ", "Foo Bar Foo".Remove ("Foo"));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Slice Method

Creates a new string of self using indexes of the start and end position.

public static string Slice (this string self, int start, int end)

⊟ Parameters

self
A string containing the string to substring.
start
A int containing the start index of the new string to create.
end
A int containing the end index of the new string to create.

⊟ Returns

A new string of self using indexes of the start and end position.

⊟ Exceptions

Type Reason
ArgumentNullException self is null.
ArgumentOutOfRangeException

start is negative

-or-

start is greater than or equal to self.Length.

-or-

end is greater than or equal to self.Length.

⊟ Remarks

This differs from System.String.Substring(System.Int32,System.Int32) in that start and end are both string indexes, while the length parameter in Substring is not an index.

If end is negative, then it is taken as a value from the end of the string.

When end is positive, this is equivalent to self.Substring (start, end - start).

C# Example 
var data = "0123456789";

Assert.AreEqual ("0",       data.Slice (0, 1));
Assert.AreEqual ("89",      data.Slice (8, 10));
Assert.AreEqual ("456789",  data.Slice (4, -1));
Assert.AreEqual ("8",       data.Slice (8, -2));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ ToEnum<TEnum> Generic Method

Converts a string into an enumeration value of type TEnum.

public static TEnum ToEnum<TEnum> (this string self)

⊟ Type Parameters

TEnum
An enumeration type containing the member stored in self.

⊟ Parameters

self
A string containing an enumeration value to convert into that enumeration value.

⊟ Returns

A TEnum value containing the value named by self.

⊟ Exceptions

Type Reason
ArgumentNullException self is null.

⊟ Remarks

Note: This probabably doesn't properly support FlagsAttribute enums...
C# Example 
Assert.AreEqual (Foo.Gazonk, "Gazonk".ToEnum<Foo> ());
Assert.AreEqual (Foo.Bar,    "Bar".ToEnum<Foo> ());

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Tokens Method

Creates an IEnumerable<string> which will return all tokens from self.

public static IEnumerable<string> Tokens (this string self, params Func<Nullable<System.Char>,System.Char,System.Boolean>[] categories)

⊟ Parameters

self
A string to extract tokens from.
categories
A Func<Nullable<System.Char>,System.Char,System.Boolean> array containing the different categories of characters that determines what makes up a "token." If the Nullable<char> parameter is null, then the char is the first character within the token; otherwise, the Nullable<char> parameter contains the character preceding the char. The delegate should return true if the char is a supported character; otherwise, false should be returned.

⊟ Returns

An IEnumerable<string> which will return all tokens from self.

⊟ Exceptions

Type Reason
ArgumentException categories is empty.
ArgumentNullException self is null, or categories is null.

⊟ Remarks

This method is implemented by using deferred execution.

Note:

A "token" is determined by categories, and is any contiguous sequence of characters for which the same categories index returns true, starting from the first delegate. This allows a "some characters are more important than others" philosphy, allowing e.g. parenthesis to be returned separately from alphanumeric characters, even if no whitespace separates them.

C# Example 
string[] expected = {"(", "hello", ",", "world", "!)"};
string[] actual = "(hello, world!)"
	.Tokens (
			(p, c) => char.IsLetterOrDigit (c), // words
			(p, c) => !char.IsWhiteSpace (c)    // non-space
	).ToArray ();
AssertAreSame (expected, actual);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ Words Method

Creates an IEnumerable<string> which will return all words from self.

public static IEnumerable<string> Words (this string self)

⊟ See Also

TextReaderCoda.Words(System.IO.TextReader)

⊟ Parameters

self
A string to extract words from.

⊟ Returns

An IEnumerable<string> which will return all words from self.

⊟ Exceptions

Type Reason
ArgumentNullException self is null.

⊟ Remarks

This method is implemented by using deferred execution.

Note: A "word" any contiguous series of characters for which char.IsWhiteSpace(char) returns false.
C# Example 
string[] expected = {"skip", "leading", "and", "trailing", "whitespace"};
string[] actual = 
	"   skip  leading\r\n\tand trailing\vwhitespace   "
	.Words ().ToArray ();
AssertAreSame (expected, actual);

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ WrappedLines Method

Splits a string into line segments with a maximum length constrained by widths.

public static IEnumerable<string> WrappedLines (this string self, IEnumerable<int> widths)

⊟ Parameters

self
A string to split into segments no longer than lenghts in the widths sequence.
widths
A IEnumerable<string> containing the maximum lengths to use for corresponding returned segments. The last value in this array is used for all remaining segments.

⊟ Returns

A IEnumerable<string> containing segments from self with a length no longer than entries from widths.

⊟ Exceptions

Type Reason
ArgumentNullException widths is null.
ArgumentOutOfRangeException widths contains a value that is less than 2.

⊟ Remarks

This is a "DWIM"-style interface for line wrapping.

WrappedLines() is oriented toward Console-style output in which line widths are controlled by the number of characters (i.e. fixed-width fonts, not proportional fonts). widths is used to constrain the length of each corresponding segment within the returned IEnumerable<string>. For example, the first string segment returned will have a length no longer than the first element in widths, the second string segment returned will have a length no longer than the second element in widths, etc. The last element in widths is used to constrain the lenghts of all remaining string segments; thus, if widths has only one element, that value is used to constrain all returned string segments.

Note that widths constrains the width of segments; a segment may be shorter, and may be empty.

String splitting is done as follows:

  1. Determine the widthto use for the current segment by getting a value from widths. If widths is empty, then the maximum segment length is int.MaxValue. If there is no remaining value in widths, use the last width value found.
  2. Beginning at index i within self (starting at index 0), look for all "end-of-line characters" -- characters for which char.IsLetterOrDigit(char) returns false, thus including punctuation, whitespace, etc. -- from self[i] until self[i+width]. If a newline is found, return the segment starting from index i until the first newline position. If no newline is found but an end-of-line character is is found, return a segment starting from index i until the last end-of-line character. If no end-of-line character is found within self[i] until self[i+width], create a segment from self[i] until self[i+width-1], and append '-' to the segment as a line-continuation character.
  3. Repeat steps 1-2 until the end of the string is encountered.
C# Example 
// Notice that the first width is 50, but the actual returned length is 17.
// This is because the newline is encountered first.
// The width of 48 is used to constrain all remaining lines, causing
// the 4th line to require line-wrapping.
//
// Notice also that all embedded '\n's are removed.
IEnumerable<string> wrappedLines =
		("This has a really\n" +
		 "long, multi-line description that also\n" +
		 "tests\n" +
		 "the-builtin-supercalifragilisticexpialidicious-break-on-hyphen.  " +
		 "Also, a list:\n" +
		 "  item 1\n" +
		 "  item 2")
		.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"This has a really",
		"long, multi-line description that also",
		"tests",
		"the-builtin-supercalifragilisticexpialidicious-",
		"break-on-hyphen.  Also, a list:",
		"  item 1",
		"  item 2",
}.SequenceEqual (wrappedLines));

// Another example where the text has no whitespace before the
// constrained width.
wrappedLines =
	"IWantThisDescriptionToBreakInsideAWordGeneratingAutoWordHyphenation."
	.WrappedLines (50, 4, 5, 12);
Assert.IsTrue (new[]{
		"IWantThisDescriptionToBreakInsideAWordGeneratingA-", // length=50
		"uto-",                                               // length=4
		"Word-",                                              // length=5
		"Hyphenation.",                                       // length=12
}.SequenceEqual (wrappedLines));

// Notice that '.' is treated as an end-of-line character
wrappedLines =
	"OnlyOnePeriod.AndNoWhitespaceShouldBeSupportedEvenWithLongDescriptions"
	.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"OnlyOnePeriod.",
		"AndNoWhitespaceShouldBeSupportedEvenWithLongDes-",
		"criptions",
}.SequenceEqual (wrappedLines));

wrappedLines =
	"Lots of spaces in the middle 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 and more until the end."
	.WrappedLines (50, 48);
Assert.IsTrue (new []{
		"Lots of spaces in the middle 1 2 3 4 5 6 7 8 9 0",
		"1 2 3 4 5 and more until the end.",
}.SequenceEqual (wrappedLines));

wrappedLines =
	"Lots of spaces in the middle - . - . - . - . - . - . - . - and more until the end."
	.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"Lots of spaces in the middle - . - . - . - . - . -",
		" . - . - and more until the end.",
}.SequenceEqual (wrappedLines));

// An ~infinite sequence of widths
wrappedLines =
	"1121231234123451234561234567123456781234567891234567890"
	.WrappedLines (Sequence.Iterate(2, v => v + 1));
Assert.IsTrue (new[]{
		"1-",
		"12-",
		"123-",
		"1234-",
		"12345-",
		"123456-",
		"1234567-",
		"12345678-",
		"123456789-",
		"1234567890",
}.SequenceEqual (wrappedLines));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0

⊟ WrappedLines Method

Splits a string into line segments with a maximum length constrained by widths.

public static IEnumerable<string> WrappedLines (this string self, params int[] widths)

⊟ Parameters

self
A string to split into segments no longer than lenghts in the widths sequence.
widths
A int array containing the maximum lengths to use for corresponding returned segments. The last value in this array is used for all remaining segments.

⊟ Returns

A IEnumerable<string> containing segments from self with a length no longer than entries from widths.

⊟ Exceptions

Type Reason
ArgumentNullException widths is null.
ArgumentOutOfRangeException widths contains a value that is less than 2.

⊟ Remarks

This is a "DWIM"-style interface for line wrapping.

WrappedLines() is oriented toward Console-style output in which line widths are controlled by the number of characters (i.e. fixed-width fonts, not proportional fonts). widths is used to constrain the length of each corresponding segment within the returned IEnumerable<string>. For example, the first string segment returned will have a length no longer than the first element in widths, the second string segment returned will have a length no longer than the second element in widths, etc. The last element in widths is used to constrain the lenghts of all remaining string segments; thus, if widths has only one element, that value is used to constrain all returned string segments.

Note that widths constrains the width of segments; a segment may be shorter, and may be empty.

String splitting is done as follows:

  1. Determine the widthto use for the current segment by getting a value from widths. If widths is empty, then the maximum segment length is int.MaxValue. If there is no remaining value in widths, use the last width value found.
  2. Beginning at index i within self (starting at index 0), look for all "end-of-line characters" -- characters for which char.IsLetterOrDigit(char) returns false, thus including punctuation, whitespace, etc. -- from self[i] until self[i+width]. If a newline is found, return the segment starting from index i until the first newline position. If no newline is found but an end-of-line character is is found, return a segment starting from index i until the last end-of-line character. If no end-of-line character is found within self[i] until self[i+width], create a segment from self[i] until self[i+width-1], and append '-' to the segment as a line-continuation character.
  3. Repeat steps 1-2 until the end of the string is encountered.
C# Example 
// Notice that the first width is 50, but the actual returned length is 17.
// This is because the newline is encountered first.
// The width of 48 is used to constrain all remaining lines, causing
// the 4th line to require line-wrapping.
//
// Notice also that all embedded '\n's are removed.
IEnumerable<string> wrappedLines =
		("This has a really\n" +
		 "long, multi-line description that also\n" +
		 "tests\n" +
		 "the-builtin-supercalifragilisticexpialidicious-break-on-hyphen.  " +
		 "Also, a list:\n" +
		 "  item 1\n" +
		 "  item 2")
		.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"This has a really",
		"long, multi-line description that also",
		"tests",
		"the-builtin-supercalifragilisticexpialidicious-",
		"break-on-hyphen.  Also, a list:",
		"  item 1",
		"  item 2",
}.SequenceEqual (wrappedLines));

// Another example where the text has no whitespace before the
// constrained width.
wrappedLines =
	"IWantThisDescriptionToBreakInsideAWordGeneratingAutoWordHyphenation."
	.WrappedLines (50, 4, 5, 12);
Assert.IsTrue (new[]{
		"IWantThisDescriptionToBreakInsideAWordGeneratingA-", // length=50
		"uto-",                                               // length=4
		"Word-",                                              // length=5
		"Hyphenation.",                                       // length=12
}.SequenceEqual (wrappedLines));

// Notice that '.' is treated as an end-of-line character
wrappedLines =
	"OnlyOnePeriod.AndNoWhitespaceShouldBeSupportedEvenWithLongDescriptions"
	.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"OnlyOnePeriod.",
		"AndNoWhitespaceShouldBeSupportedEvenWithLongDes-",
		"criptions",
}.SequenceEqual (wrappedLines));

wrappedLines =
	"Lots of spaces in the middle 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 and more until the end."
	.WrappedLines (50, 48);
Assert.IsTrue (new []{
		"Lots of spaces in the middle 1 2 3 4 5 6 7 8 9 0",
		"1 2 3 4 5 and more until the end.",
}.SequenceEqual (wrappedLines));

wrappedLines =
	"Lots of spaces in the middle - . - . - . - . - . - . - . - and more until the end."
	.WrappedLines (50, 48);
Assert.IsTrue (new[]{
		"Lots of spaces in the middle - . - . - . - . - . -",
		" . - . - and more until the end.",
}.SequenceEqual (wrappedLines));

// An ~infinite sequence of widths
wrappedLines =
	"1121231234123451234561234567123456781234567891234567890"
	.WrappedLines (Sequence.Iterate(2, v => v + 1));
Assert.IsTrue (new[]{
		"1-",
		"12-",
		"123-",
		"1234-",
		"12345-",
		"123456-",
		"1234567-",
		"12345678-",
		"123456789-",
		"1234567890",
}.SequenceEqual (wrappedLines));

⊟ Requirements

Namespace: Cadenza
Assembly: Cadenza (in Cadenza.dll)
Assembly Versions: 0.1.0.0