# Io Reference

Core / Core / Sequence

A Sequence is a container for a list of data elements. Typically these elements are each 1 byte in size. A Sequence can be either mutable or immutable. When immutable, only the read-only methods can be used.

Terminology

- Buffer: A mutable Sequence of single byte elements, typically in a binary encoding
- Symbol or String: A unique immutable Sequence, typically in a character encoding

*(aSeq)

Multiplies the values of aSeq to the corresponding values of the receiver returning a new vector with the result. Only works on Sequences whose item type is numeric.
*=(aSeq)

Multiplies the values of aSeq to the corresponding values of the receiver. Only works on Sequences whose item type is numeric. Returns self.
+(aSeq)

Vector addition - Adds the values of aSeq to the corresponding values of the receiver returning a new vector with the result. Only works on Sequences whose item type is numeric.
+=(aSeq)

Vector addition - adds the values of aSeq to those of the receiver. Only works on Sequences whose item type is numeric. Returns self.
-=(aSeq)

Vector subtraction - subtracts the values of aSeq to those of the receiver. Only works on Sequences whose item type is numeric. Returns self.
..(aSequence)

Returns a copy of the receiver with aSequence appended to it.
/(aSeq)

Divides the values of aSeq to the corresponding values of the receiver returning a new vector with the result. Only works on Sequences whose item type is numeric.
/=(aSeq)

Divides the values of aSeq to the corresponding values of the receiver. Only works on Sequences whose item type is numeric. Returns self.
Max

Returns the maximum value in the sequence.
Min

Returns the minimum value in the sequence.
abs

Sets each value of the Sequence to its absolute value. Returns self.
acos

Sets each value of the Sequence to the trigonometric arcsine of it's value. Returns self.
afterSeq(aSequence)

Returns the slice of the receiver (as a Symbol) after aSequence or nil if aSequence is not found. If aSequence is empty, the receiver (or a copy of the receiver if it is mutable) is returned.
alignCenter(width, [padding]) ""

Example: `Io> "abc" alignCenter(10, "-") ==> ---abc---- Io> "abc" alignCenter(10, "-=") ==> -=-abc-=-=`
alignLeft(width, [padding])

Example:

`Io> "abc" alignLeft(10, "+") ==> abc+++++++ Io> "abc" alignLeft(10, "-=") ==> abc-=-=-=-`

alignLeftInPlace(width, [padding])

Same as align left but operation is performed on the receiver.
alignRight(width, [padding])

Example:

`Io> "abc" alignRight(10, "-") ==> -------abc Io> "abc" alignRight(10, "-=") ==> -=-=-=-abc`

allMatchesOfRegex(aRegexOrString)

Returns a List containing all matches of the given regex found in the receiver.
append(aNumber)

Appends aNumber (cast to a byte) to the receiver. Returns self.
appendPathSeq(aSeq)

Appends argument to the receiver such that there is one and only one path separator between the two. Returns self.
appendSeq(object1, object2, ...)

Calls asString on the arguments and appends the string to the receiver. Returns self.
asBase64(optionalCharactersPerLine)

Returns an immutable, base64 encoded (according to RFC 1421) version of self. optionalCharactersPerLine describes the number of characters between line breaks and defaults to 0.
asBinaryNumber

Returns a Number containing the first 8 bytes of the receiver without casting them to a double. Endian is same as machine.
asBinarySignedInteger

Returns a Number with the bytes of the receiver interpreted as a binary signed integer. Endian is same as machine.
asBinaryUnsignedInteger

Returns a Number with the bytes of the receiver interpreted as a binary unsigned integer. Endian is same as machine.
asCapitalized

Returns a copy of the receiver with the first charater made uppercase.
asClutterColor

Calls [[ClutterColor with]] with self as an argument.
asClutterUnit

Calls [[ClutterUnit withString]].
asFile

Returns a new File object with the receiver as its path.
asFixedSizeType

Returns a new sequence with the receiver encoded in the minimal fixed width text encoding that its characters can fit into (either, ascii, utf8, utf16 or utf32).
asHTML

SGML extension to interpret the Sequence as HTML and return an SGML object using SGMLParser elementForString
asHex

Returns a hex string for the receiving sequence, e.g., \"abc\" asHex -> \"616263\".")
asIoPath

Returns a Io style path for an OS style path.
asJid

Converts Sequence to JID object.

    "cow@moo.com/Scandinavia" asJid

asJson

Converts to form that could be interpreted as json if it already contains json, e.g. {"aaa":"bbb"} --> "{\"aaa\":\"bbb\"}"
asLowercase

Returns a symbol containing the reveiver made lowercase.
asMessage(optionalLabel)

Returns the compiled message object for the string.
asMutable

Returns a mutable copy of the receiver.
asNumber

Returns the receiver converted to a number. Initial whitespace is ignored.
asOSPath

Returns a OS style path for an Io style path.
asRegex

Returns a new Regex created from the receiver.
asSGML

SGML extension to interpret the Sequence as SGML and return an SGML object using SGMLParser elementForString
asStruct(memberList)

For a sequence that contains the data for a raw memory data structure (as used in C), this method can be used to extract its members into an Object. The memberList argument specifies the layout of the datastructure. Its form is:

list(memberType1, memberName1, memberType2, memberName2, ...)

Member types include:

    int8, int16, int32, int64
    uint8, uint16, uint32, uint64
    float32, float64

Example:

    pointObject := structPointSeq asStruct(list("float32", "x", "float32", "y"))

The output pointObject would contain x and y slots with Number objects.
asSymbol

Returns a immutable Sequence (aka Symbol) version of the receiver.
asUCS2

Returns a new copy of the receiver converted to UCS2 (fixed character width UTF16) encoding.
asUCS4

Returns a new copy of the receiver converted to UCS4 (fixed character width UTF32) encoding.
asURL

Returns a new URL object instance with the receiver as its url string.
asUTF8

Returns a new copy of the receiver converted to utf8 encoding.
asUppercase

Returns a symbol containing the reveiver made uppercase.
asUrl

Shortcut for HCUrl with(aUrlSeq)
asXML

SGML extension to interpret the Sequence as XML and return an SGML object using SGMLParser elementForString
asin

Sets each value of the Sequence to the trigonometric arcsine of it's value. Returns self.
at(aNumber)

Returns a value at the index specified by aNumber. Returns nil if the index is out of bounds.
atInsertSeq(indexNumber, object)

Calls asString on object and inserts the string at position indexNumber. Returns self.
atPut(aNumberIndex, aNumber)

Sets the value at the index specified by aNumberIndex to aNumber. Returns self.
atan

Sets each value of the Sequence to the trigonometric arctangent of it's value. Returns self.
beforeSeq(aSequence)

Returns the slice of the receiver (as a Symbol) before aSequence or self if aSequence is not found.
beginsWithSeq(aSequence)

Returns true if the receiver begins with aSequence, false otherwise.
betweenSeq(aSequence, anotherSequence)

Returns a new Sequence containing the bytes between the occurrence of aSequence and anotherSequence in the receiver. If aSequence is empty, this method is equivalent to beforeSeq(anotherSequence). If anotherSequence is nil, this method is equivalent to afterSeq(aSequence). nil is returned if no match is found.
bitAt(bitIndex)

Returns a Number containing the bit at the bit index value.
bitCount

Returns the number of bits in the sequence.
bitwiseAnd(aSequence)

Updates the receiver to be the result of a bitwiseAnd with aSequence. Returns self.
bitwiseNot(aSequence)

Updates the receiver to be the result of a bitwiseNot with aSequence. Returns self.
bitwiseOr(aSequence)

Updates the receiver to be the result of a bitwiseOr with aSequence. Returns self.
bitwiseXor(aSequence)

Updates the receiver to be the result of a bitwiseXor with aSequence. Returns self.
byteAt(byteIndex)

Returns a Number containing the byte at the byte index value.
capitalize

First charater of the receiver is made uppercase.
ceil

Round each value to smallest integral value not less than x. Returns self.
clear

Set all values in the sequence to 0. Returns self.
clipAfterSeq(aSequence)

Removes the contents of the receiver after the end of the first occurance of aSequence. Returns true if anything was removed, or false otherwise.
clipAfterStartOfSeq(aSequence)

Removes the contents of the receiver after the beginning of the first occurance of aSequence. Returns true if anything was removed, or false otherwise.
clipBeforeEndOfSeq(aSequence)

Removes the contents of the receiver before the end of the first occurance of aSequence. Returns true if anything was removed, or false otherwise.
clipBeforeSeq(aSequence)

Clips receiver before aSequence.
cloneAppendPath(aSequence)

Appends argument to a copy the receiver such that there is one and only one path separator between the two and returns the result.
contains(aNumber)

Returns true if the receiver contains an element equal in value to aNumber, false otherwise.
containsAnyCaseSeq(aSequence)

Returns true if the receiver contains the aSequence regardless of casing, false otherwise.
containsSeq(aSequence)

Returns true if the receiver contains the substring aSequence, false otherwise.
convertToItemType(aTypeName)

Converts the underlying machine type for the elements, expanding or contracting the size of the Sequence as needed. Valid names are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32, and float64. Note that 64 bit types are only available on platforms that support such types. Returns self.
copy(aSequence)

Replaces the bytes of the receiver with a copy of those in aSequence. Returns self.
cos

Sets each value of the Sequence to the trigonometric cosine of it's value. Returns self.
cosh

Sets each value of the Sequence to the hyperbolic cosine of its value. Returns self.
distanceTo(aSeq)

Returns a number with the square root of the sum of the square of the differences of the items between the sequences.
dotProduct(aSeq)

Returns a new Sequence containing the dot product of the receiver with aSeq.
duplicateIndexes

Duplicates all indexes in the receiver. For example, list(1,2,3) duplicateIndexes == list(1,1,2,2,3,3). Returns self.
empty

Sets all bytes in the receiver to 0x0 and sets its length to 0. Returns self.
encoding

Returns the encoding of the elements.
endsWithSeq(aSequence)

Returns true if the receiver ends with aSequence, false otherwise.
escape

Escape characters in the receiver are replaced with escape codes. For example a string containing a single return character would contain the following 2 characters after being escaped: "\n". Returns self.
escapeRegexChars

Returns a clone of the receiver with all special regular expression characters ("^", "$", etc) backslashed. Useful if you have a string that contains such characters, but want it to be treated as a literal string.
exclusiveSlice(inclusiveStartIndex, exclusiveEndIndex)

Returns a new string containing the subset of the receiver from the inclusiveStartIndex to the exclusiveEndIndex. The exclusiveEndIndex argument is optional. If not given, it is assumed to be one beyond the end of the string.
exp

Sets each value of the Sequence to e**value. Returns self.
fileName

Returns the last path component sans the path extension.
findNthSeq(aSequence, n)

Returns a number with the nth occurence of aSequence.
findRegex(aRegexOrString, [startIndex])

Returns the first match of the given regex in the receiver, after the given start index. If you don't specify a start index, the search will start at the beginning of the receiver. The method returns nil if no match is found.
findSeq(aSequence, optionalStartIndex)

Returns a number with the first occurrence of aSequence in the receiver after the startIndex. If no startIndex is specified, the search starts at index 0. nil is returned if no occurences are found.
findSeqs(listOfSequences, optionalStartIndex)

Returns an object with two slots - an \"index\" slot which contains the first occurrence of any of the sequences in listOfSequences found in the receiver after the startIndex, and a \"match\" slot, which contains a reference to the matching sequence from listOfSequences. If no startIndex is specified, the search starts at index 0. nil is returned if no occurences are found.
floor

Round each value to largest integral value not greater than x. Returns self.
foreach(optionalIndex, value, message)

For each element, set index to the index of the element and value to the element value and execute message. Example:

    aSequence foreach(i, v, writeln("value at index ", i, " is ", v))
    aSequence foreach(v, writeln("value ", v))

fromBase(aNumber)

Returns a number with a base 10 representation of the receiver converted from the specified base. Only base 2 through 32 are currently supported.
fromBase64

Returns an immutable, base64 decoded (according to RFC 1421) version of self.
greaterThan(aSeq)

Returns true if the receiver is greater than aSeq, false otherwise.
greaterThanOrEqualTo(aSeq)

Returns true if the receiver is greater than or equal to aSeq, false otherwise.
hasMatchOfRegex(aRegexOrString)

Returns true if the string contains one or more matches of the given regex.
hash

Returns a Number containing a hash of the Sequence.
inclusiveSlice(inclusiveStartIndex, inclusiveEndIndex)

Returns a new string containing the subset of the receiver from the inclusiveStartIndex to the inclusiveEndIndex. The inclusiveEndIndex argument is optional. If not given, it is assumed to be the end of the string.
interpolate(ctx)

Returns immutable copy of self with interpolateInPlace(ctx) passed to the copy.
interpolateInPlace(optionalContext)

Replaces all #{expression} with expression evaluated in the optionalContext. If optionalContext not given, the current context is used. Returns self.
isEmpty

Returns true if the size of the receiver is 0, false otherwise.
isEqualAnyCase(aSequence)

Returns true if aSequence is equal to the receiver ignoring case differences, false otherwise.
isLowercase

Returns self if all the characters in the string are lower case.
isMutable

Returns true if the receiver is a mutable Sequence or false otherwise.
isSymbol

Returns true if the receiver is a immutable Sequence (aka, a Symbol) or false otherwise.
isUppercase

Returns self if all the characters in the string are upper case.
isZero

Returns true if all elements are 0, false otherwise.
itemCopy

Returns a new sequence containing the items from the receiver.
itemSize

Returns number of bytes in each element.
itemType

Returns machine type of elements.
justSerialized(stream)

Writes the receiver's code into the stream.
lastPathComponent

Returns a string containing the receiver clipped up to the last path separator.
lessThan(aSeq)

Returns true if the receiver is less than aSeq, false otherwise.
lessThanOrEqualTo(aSeq)

Returns true if the receiver is less than or equal to aSeq, false otherwise.
linePrint

Prints the Sequence and a newline character.
log

Sets each value of the Sequence to the natural log of its value. Returns self.
log10

Sets each value of the Sequence to the base 10 log of its value. Returns self.
logicalAnd(aSequence)

Updates the receiver's values to be the result of a logical OR operations with the values of aSequence. Returns self.
logicalOr(aSequence)

Updates the receiver's values to be the result of a logical OR operations with the values of aSequence. Returns self.
lowercase

Makes all the uppercase characters in the receiver lowercase. Returns self.
lstrip(aSequence)

Strips the characters in aSequence stripped from the beginning of the receiver. Example:

    "Keep the tail" lstrip(" eKp")
    ==> "the tail"

makeFirstCharacterLowercase

Receiver must be mutable (see also asMutable). Returns receiver.

      Io> "ABC" asMutable makeFirstCharacterLowercase
      ==> aBC

makeFirstCharacterUppercase

Receiver must be mutable (see also asMutable). Returns receiver.

      Io> "abc" asMutable makeFirstCharacterUppercase
      ==> Abc

matchesOfRegex(aRegexOrString)

Returns a RegexMatches object that enumerates all matches of the given regex in the receiver.
matchesRegex(aRegexOrString)

Returns true if the receiver matches the given regex, false if not.
max

Returns the maximum value of the Sequence.
mean

Returns the arithmetic mean of the sequence.
meanSquare

Returns the arithmetic mean of the sequence's values after they have been squared.
min

Returns the minimum value of the Sequence.
negate

Negates the values of the receiver. Returns self.
normalize

Divides each value of the Sequence by the max value of the sequence. Returns self.
occurancesOfSeq(aSeq)

Returns count of aSeq in the receiver.
pathComponent

Returns a slice of the receiver before the last path separator as a symbol.
pathExtension

Returns a string containing the receiver clipped up to the last period.
percentDecoded

Returns percent decoded version of receiver.
percentEncoded

Returns percent encoded version of receiver.
preallocateToSize(aNumber)

If needed, resize the memory alloced for the receivers byte array to be large enough to fit the number of bytes specified by aNumber. This is useful for pio_reallocating the memory so it doesn't keep getting allocated as the Sequence is appended to. This operation will not change the Sequence's length or contents. Returns self.
prependSeq(object1, object2, ...)

Prepends given objects asString in reverse order to the receiver. Returns self.")
print

Prints contents of a sequence.
product

Returns the product of all the sequence's values multipled together.
rangeFill

Sets the values of the Sequence to their index values. Returns self.
removeAt(index)

Removes the item at index. Returns self.
removeEvenIndexes

Removes even indexes in the receiver. For example, list(1,2,3) removeEvenIndexes == list(1, 3). Returns self.
removeLast

Removes the last element from the receiver. Returns self.
removeOddIndexes

Removes odd indexes in the receiver. For example, list(1,2,3) removeOddIndexes == list(2). Returns self.
removePrefix(aSequence)

If the receiver begins with aSequence, it is removed. Returns self.
removeSeq(aSequence)

Removes occurances of aSequence from the receiver.
removeSlice(startIndex, endIndex)

Removes the items from startIndex to endIndex. Returns self.
removeSuffix(aSequence)

If the receiver end with aSequence, it is removed. Returns self.
repeated(n)

Returns a new sequence containing the receiver repeated n number of times.
replaceFirstSeq(aSequence, anotherSequence, optionalStartIndex)

Returns a new Sequence with the first occurance of aSequence replaced with anotherSequence in the receiver. If optionalStartIndex is provided, the search for aSequence begins at that index. Returns self.
replaceMap(aMap)

In the receiver, the keys of aMap replaced with its values. Returns self.
replaceSeq(aSequence, anotherSequence)

Returns a new Sequence with all occurances of aSequence replaced with anotherSequence in the receiver. Returns self.
reverse

Reverses the ordering of all the items of the receiver. Returns copy of receiver.
reverseFindSeq(aSequence, startIndex)

Returns a number with the first occurrence of aSequence in the receiver before the startIndex. The startIndex argument is optional. By default reverseFind starts at the end of the string. Nil is returned if no occurrences are found.
reverseInPlace

Reverses the bytes in the receiver, in-place.
rstrip(aSequence)

Strips the characters in aSequence stripped from the end of the receiver. Example:

    "Cut the tail off" rstrip(" afilot")
    ==> "Cut the"

set(aNumber1, aNumber2, ...)

Sets the values of the receiver to the sequences of numbers in the arguments. Unset values will remain unchanged. Returns self.
setEncoding(encodingName)

Sets the encoding flag of the receiver (only the encoding flag, itemSize and itemType will change, no conversion is done between UTF encodings - you can use convertToUTF8, etc methods for conversions). Valid encodings are number, utf8, utf16, and utf32. Returns self.
setItemType(aTypeName)

Sets the underlying machine type for the elements. Valid names are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32, and float64. Note that 64 bit types are only available on platforms that support such types. Returns self.
setItemsToDouble(aNumber)

Sets all items in the Sequence to the double floating point value of aNumber.
setItemsToLong(aNumber)

Sets all items in the Sequence to the long integer value of aNumber.
setSize(aNumber)

Sets the length in bytes of the receiver to aNumber. Return self.
sin

Sets each value of the Sequence to the trigonometric sine of it's value. Returns self.
sinh

Sets each value of the Sequence to the hyperbolic sine of its value. Returns self.
size

Returns the length in number of items (which may or may not be the number of bytes, depending on the item type) of the receiver. For example,

    "abc" size == 3

sizeInBytes

Returns the length in bytes of the receiver.
slice

Deprecated method. Use exSlice instead.
slicesBetween(startSeq, endSeq)

Returns a list of slices delimited by `startSeq` and `endSeq`.

      Io> "" slicesBetween("<", ">")
      ==> list("a", "b", "/b", "/a")

sort

Sorts the characters/numbers in the array. Returns self.
split Returns a list containing the sub-sequences of the receiver divided by the given arguments.

If no arguments are given the sequence is split on white space.
split(optionalArg1, optionalArg2, ...)

Returns a list containing the sub-sequences of the receiver divided by the given arguments. If no arguments are given the sequence is split on white space. Examples:

    "a b c d" split == list("a", "b", "c", "d")
    "a*b*c*d" split("*") == list("a", "b", "c", "d")
    "a*b|c,d" split("*", "|", ",") == list("a", "b", "c", "d")
    "a   b  c d" split == list("a", "", "", "", "b", "", "", "c", "", "d")

splitAt(indexNumber)

Returns a list containing the two parts of the receiver as split at the given index.
splitAtRegex(aRegexOrString)

Splits the receiver into pieces using the given regex as the delimiter and returns the pieces as a list of strings.
splitNoEmpties(optionalArg1, optionalArg2, ...)

Returns a list containing the non-empty sub-sequences of the receiver divided by the given arguments. If no arguments are given the sequence is split on white space. Examples: `"a b c d" splitNoEmpties => list("a", "b", "c", "d") "a***b**c*d" splitNoEmpties("*") => list("a", "b", "c", "d") "a***b||c,d" splitNoEmpties("*", "|", ",") => list("a", "b", "c", "d")`
sqrt

Sets each value of the Sequence to the square root of its value. Returns self.
square

Sets each value of the Sequence to the square of its value. Returns self.
strip(optionalSequence)

Trims the whitespace (or optionalSequence) off both ends:

    "   Trim this string   \r\n" strip
    ==> "Trim this string"

sum

Returns the sum of the Sequence.
tan

Sets each value of the Sequence to the trigonometric tangent of it's value. Returns self.
tanh

Sets each value of the Sequence to the hyperbolic tangent of its value. Returns self.
toBase(aNumber)

Returns a Sequence containing the receiver (which is assumed to be a base 10 number) converted to the specified base. Only base 8 and 16 are currently supported.
translate(fromChars, toChars)

In the receiver, the characters in fromChars are replaced with those in the same positions in toChars. Returns self.
unescape

Escape codes replaced with escape characters. Returns self.
uppercase

Makes all characters of the receiver uppercase.
urlDecoded

Returns url decoded version of receiver.
urlEncoded

Returns url encoded version of receiver.
whiteSpaceStrings

Returns a List of strings. Each string contains a different whitespace character.
with(aSequence, ...)

Returns a new Sequence which is the concatination of the arguments. The returned sequence will have the same mutability status as the receiver.
withStruct(memberList)

This method is useful for producing a Sequence containing a raw datastructure with the specified types and values. The memberList format is:

list(memberType1, memberName1, memberType2, memberName2, ...)

Member types include:

    int8, int16, int32, int64
    uint8, uint16, uint32, uint64
    float32, float64

Example:

    pointStructSeq := Sequence withStruct(list("float32", 1.2, "float32", 3.5))

The output pointStructSeq would contain 2 raw 32 bit floats.