2.5.4. Bytes

TODO.

2.5.4.1. Instruction

bytes.append op1 op2 [bytes::Append]

Operator 1:ref<bytes> Operator 2:ref<bytes>

Appends op2 to op1. The two operands must not refer to the same object. Raises ValueError if op1 has been frozen, or if op1 is the same as op2.

bytes.append_mark op1 [bytes::AppendMark]

Operator 1:ref<bytes>

Inserts a mark right after the current end of bytes object op1. When later more bytes get added, the mark will be pointing to the first of them.

bytes.append_object op1 op2 [bytes::AppendObject]

Operator 1:ref<bytes> Operator 2:any

Inserts a separator object op2 to the end of the bytes object op1. When iterating over a bytes object, reaching the object will generally be treated as if the end has been reached. However, the instructions retrieve_object/at_object/skip_object may be used to operate on the inserted objects.

target = bytes.at_mark op1 [bytes::AtMark]

Target:bool Operator 1:iterator<bytes>

Returns True if there’s a mark at the iterator position op1.

target = bytes.at_object op1 op2 [bytes::AtObject]

Target:bool Operator 1:iterator<bytes> Operator 2:[ (no type) ]

Checks if there’s a separator object located at the iterator position op1. If op2 is given, confirms that the object is of the corresponding type as well.

target = bytes.cmp op1 op2 [bytes::Cmp]

Target:int<8> Operator 1:ref<bytes> Operator 2:ref<bytes>

Compares op1 with op2 lexicographically. If op1 is larger, returns -1. If both are equal, returns 0. If op2 is larger, returns 1.

target = bytes.concat op1 op2 [bytes::Concat]

Target:ref<bytes> Operator 1:ref<bytes> Operator 2:ref<bytes>

Concatentates op2 to op1, returning a new bytes object.

target = bytes.contains op1 op2 [bytes::Contains]

Target:bool Operator 1:ref<bytes> Operator 2:ref<bytes>

Returns true if op1 contains op2 as a subsequence.

target = bytes.copy op1 [bytes::Copy]

Target:ref<bytes> Operator 1:ref<bytes>

Copy the contents of op1 into a new byte instance.

target = bytes.diff op1 op2 [bytes::Diff]

Target:int<64> Operator 1:iterator<bytes> Operator 2:iterator<bytes>

Returns the number of bytes between op1 and op2.

target = bytes.empty op1 [bytes::Empty]

Target:bool Operator 1:ref<bytes>

Returns true if op1 is empty. Note that using this instruction is more efficient than comparing the result of bytes.length to zero.

target = bytes.find op1 op2 [bytes::FindAtIter]

Target:tuple<*> Operator 1:iterator<bytes> Operator 2:ref<bytes>

Searches op2 from position op1 onwards. Returns a tuple of a boolean and an iterator. If op2 was found, the boolean will be true and the iterator pointing to the first occurance. If op2 was not found, the boolean will be false and the iterator will point to the last position so that everything before that is guaranteed to not contain even a partial match of op1 (in other words: one can trim until that position and then restart the search from there if more data gets appended to the underlying bytes object.

bytes.freeze op1 [bytes::Freeze]

Operator 1:ref<bytes>

Freezes the bytes object op1. A frozen bytes object cannot be further modified until unfrozen. If the object is already frozen, the instruction is ignored.

target = bytes.index op1 [bytes::Index]

Target:int<64> Operator 1:iterator<bytes>

Returns offset of the byte op1 refers to relative to the beginning of the underlying byte object.

target = bytes.is_frozen op1 [bytes::IsFrozenIterBytes]

Target:bool Operator 1:iterator<bytes>

Returns whether the bytes object referenced by the iterator op1 has been frozen.

target = bytes.join op1 op2 [bytes::Join]

Target:ref<bytes> Operator 1:ref<bytes> Operator 2:ref<list<*>>

Renders each of the elements in list op2 into a bytes object (as if one printed it), and then concatenates them using op1 as the separator.

target = bytes.length op1 [bytes::Length]

Target:int<64> Operator 1:ref<bytes>

Returns the number of bytes stored in op1.

target = bytes.lower op1 [bytes::Lower]

Target:ref<bytes> Operator 1:ref<bytes>

Returns a lower-case version of the bytes object op1.

target = bytes.next_mark op1 [bytes::NextMark]

Target:iterator<bytes> Operator 1:iterator<bytes>

Moves the iterator op1 to the position of the next mark, or to then end if there’s no further mark. Returns the current position if that’s pointing to a mark already.

target = bytes.next_object op1 [bytes::NextObject]

Target:iterator<bytes> Operator 1:iterator<bytes>

Advances iterator op1 up to the next embedded object, returning the new iterator or the end position of none.

target = bytes.offset op1 op2 [bytes::Offset]

Target:iterator<bytes> Operator 1:ref<bytes> Operator 2:int<64>

Returns an iterator representing the offset op2 in op1.

target = bytes.retrieve_object op1 [bytes::RetrieveObject]

Target:any Operator 1:iterator<bytes>

Retrieves a separator object at a iterator position op1. The object’s type must match the target type, otherwise will throw a TypeError. If no separator object at the position, throws a \c ValuesError.

target = bytes.skip_object op1 [bytes::SkipObject]

Target:iterator<bytes> Operator 1:iterator<bytes>

Advances iterator op1 past an object, returning the new iterator. Throws ValueError if there’s no object at the location.

target = bytes.split op1 op2 [bytes::Split]

Target:ref<vector<*>> Operator 1:ref<bytes> Operator 2:ref<bytes>

Splits bytes object op1 at each occurence of separator op2, and return a vector with the individual pieces and the separator removes. If the separator is not found, the returned vector will just have op1 as a single element. If the separator is not given, or empty, the split will take place a sequences of white space.

target = bytes.split1 op1 op2 [bytes::Split1]

Target:tuple<*> Operator 1:ref<bytes> Operator 2:ref<bytes>

Splits bytes object op1 at the first occurence of separator op2, and return the two parts as a tuple of bytes object. If the separator is not found, the returned tuple will have op1 as its first element and an empty bytes object as its second. If the separator is not given, or empty, the split will take place a sequences of white space.

target = bytes.startswith op1 op2 [bytes::StartsWith]

Target:bool Operator 1:ref<bytes> Operator 2:ref<bytes>

Returns True if the bytes object op1 starts with op2.

target = bytes.strip op1 op2 op3 [bytes::Strip]

Target:ref<bytes> Operator 1:ref<bytes> Operator 2:[ enum { } ] Operator 3:[ ref<bytes> ]

Removes leading and trailing sequences of any characters in op2 from the bytes object op1. If op2 is not given, removes white-space. If op3 is given, it must be of type Hilti::Side and indicates which side of op1 should be stripped. Default is Hilti::Side::Both.

target = bytes.sub op1 op2 [bytes::Sub]

Target:ref<bytes> Operator 1:iterator<bytes> Operator 2:iterator<bytes>

Extracts the subsequence between op1 and op2 from an existing bytes instance and returns it in a new bytes instance. The element at op2 is not included.

target = bytes.to_int op1 op2 [bytes::ToIntFromBinary]

Target:int<64> Operator 1:ref<bytes> Operator 2:enum { }

Converts a bytes object op1 into a signed integer, assuming it’s encoded in a binary represention with byte order op2.

target = bytes.to_uint op1 op2 [bytes::ToUIntFromBinary]

Target:int<64> Operator 1:ref<bytes> Operator 2:enum { }

Converts a bytes object op1 into an unsigned integer, assuming it’s encoded in a binary represention with byte order op2.

bytes.trim op1 op2 [bytes::Trim]

Operator 1:ref<bytes> Operator 2:iterator<bytes>

Trims the bytes object op1 at the beginning by removing data up to (but not including) the given position op2. The iterator op2 will remain valid afterwards and still point to the same location, which will now be the first of the bytes object. Note: The effect of this instruction is undefined if the given iterator op2 does not actually refer to a location inside the bytes object op1.

bytes.unfreeze op1 [bytes::Unfreeze]

Operator 1:ref<bytes>

Unfreezes the bytes object op1. An unfrozen bytes object can be further modified. If the object is already unfrozen (which is the default), the instruction is ignored.

target = bytes.upper op1 [bytes::Upper]

Target:ref<bytes> Operator 1:ref<bytes>

Returns an upper-case version of the bytes object op1.

target = incr_by op1 op2 [iterBytes::IncrBy]

Target:iterator<bytes> Operator 1:iterator<bytes> Operator 2:int<64>

Advances the iterator by op2 elements, or to the end position if that is reached during the process.