mirrors/janet
1
0
Fork 0
mirror of https://github.com/janet-lang/janet synced 2025-02-03 02:39:09 +00:00
Code Issues 1 Releases Wiki Activity

Clarify documentation of contains?

Browse Source 
Also contains-value?
This commit is contained in:
Techcable 2022-08-26 15:17:20 -07:00
parent 927e9e4e4d
commit 754b61c593
No known key found for this signature in database
GPG Key ID: D7B98ADFF827CD17
1 changed files with 25 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/boot/boot.janet
View File

@ -1205,8 +1205,8 @@
Semantically equivalent to `(not (nil? (get collection key)))`.
Arrays, tuples, and buffer types (string/keyword) are indexed by integer keys.
For those types, this function simply checks if the index is valid.
Arrays, tuples, and buffer types (string, buffer, keyword, symbol) are all indexed by integer keys.
For those types, this function simply checks if the index is less than the length.
If this function succeeds, then a call to `(in collection key)` is guarenteed
to succeed as well.
@ -1216,22 +1216,24 @@
(not (nil? (get collection key))))
(defn contains?
```Checks if a collection, buffer, or any other iterable type contains the specified value.
```Checks if a collection contains the specified value.
For tables and structs, this only checks the keys,
and not the values.
This supports any iterable type by way of the `next` function.
This includes buffers, dictionaries, arrays, fibers, and possibly abstract types.
For arrays and tuples this takes O(n) time,
while for tables and structs this takes (average) O(1) time.
For tables and structs, this checks the values, not the keys.
For arrays, tuples (and any other iterable type), this simply checks if any of the values are eqyak.
Warning: For buffer types (strings, buffers, keywords), this checks if the specified byte is present.
Technically, buffers and strings are an iterable type, they will also work with `next` and `index-of`.
For buffer types (strings, buffers, keywords), this checks if the specified byte is present.
This is because, buffer types (strings, keywords, symbols) are iterable types, with byte values.
This means they will also work with `next` and `index-of`.
However, it also means this function will not check for substrings, only integer bytes.
In other words is `(contains? "foo bar" "foo")` is always false, because "foo" is not an integer byte
If you want to check for a substring in a buffer, then use `(not (nil? (string/find substr buffer)))`
If the type is not iterable, this will return false.
NOTE on strings: `(contains? str val) will only check for byte values of `val`, not substrings.
In other words is `(contains? "foo bar" foo") will return false (because "foo" is not an integer byte).
If you want to check for a substring in a buffer, then use `(not (nil? (string/find substr :foo)))`
This is in contrast to `index-of` and `next`, which will throw a type error.
In general this function has O(n) performance, since it requires iterating over all the values.
@ -1239,7 +1241,7 @@
[collection val]
# NOTE: index-of throws excpetion if `collection` is not iterable
#
# guard against that
# We want to guard against that
(try (not (nil? (index-of val collection))) false))