GoFiler Legato Script Reference   Legato v 1.5d Application v 5.25a

Table of Contents	< < Previous	Next >>

 

Chapter Eight — Data Functions (continued)

BinarySearchList Function

Overview

The BinarySearchList function performs a binary search of a sorted list.

Syntax/Parameters

Syntax

int = BinarySearchList ( string list[], string target, [int mode] );

Parameters

list

An array of string data which must resolve to a single dimension.

target

A string to search for within the list (array).

mode

An optional int specifying a match mode as defined below. The default mode is SORT_ALPHA.

Return Value

Returns an int specifying the matching index position or -1 if the item is not found. When not found, the last error will contain the next index position after where the item would have been in the list. Use the GetLastError function to retrieve error code and index information. Note that the index can be passed the last position if the pattern is larger (or smaller in descending mode) than the last position

Remarks

A binary search employs an algorithm that finds the position of a target value within a sorted array. A binary search compares the target value to the center of the array; if they are unequal, the half in which the target cannot lie is eliminated and the search continues on the remaining half until it is successful. When the list can no longer be halved, the search ends.

Binary search is very fast requiring only log2(n) + 1 iterations. For example, searching a list of 128,000 items will only require 18 compares to eliminate the target on the list or less than 18 to actually match the item. However, it requires the list to be sorted in the same mode as the search. The modes are as follows:

	Term			Code		Description
	Types (select one)
		SORT_ALPHA		0x00000000		Sorted As Text
		SORT_ALPHA_NUMERIC		0x00000001		Sorted As Text Expand Numbers — Numeric values are blown out for comparison such that 12 will precede 100.
		SORT_NUMERIC		0x00000002		Loose Numeric Matching — Each field is converted to a number using the logic of TextToInteger and then compared.
		SORT_DATE		0x00000003		Date Mode — Each field is converted to a date value using the loose conversion and then compared.
	Options
		SORT_ASCENDING		0x00000000		Sorted Ascending Order (default)
		SORT_DESCENDING		0x00001000		Sorted Descending Order
		SORT_NO_CASE		0x00004000		Not Case-Sensitive (does not apply to SORT_NUMERIC or SORT_DATE)

 

The last error will also contain the index with ERROR_SOFT ORed if the item was not found. When not found, the index will be the next larger item. For example, if the list contains “a”, “b”, “c”, “d”, “f”, “g”, and “h” and the target is “e”, the return value will be -1 and the last error will be 0x80000004, pointing to “f”, the next larger item in the list. If there is no larger item, the error index will be the same as the depth, or 1 plus the last item index. This allows for an insert point or the ability to iterate items from a certain point. For example, all items after the letter ‘N’.

If items are inserted in to the list in the correct order, the list will not require resorting for subsequent searches.

Related Functions

BinarySearchList — Performs a binary search of a list.

DeleteListItem — Removes item or items from a list.

DeleteTableRow — Removes row or rows from a table.

FindInList — Performs a linear search for an item in a list (single-dimension array) with options and starting string index.

FindInTable — Performs a linear search for an item in a table (two-dimensional array) with column, options, and string index.

InsertListItem — Inserts empty item or items to a list.

ScanString — Scans a string as a list delimited by spaces, commas, or line endings.

SortList — Sorts a list (single-dimensional array) with options.

SortTable — Sorts a table (two-dimensional array) with options and specified columns.

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

Page revised 2024-12-13

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 12/16/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.