diff --git a/docs/construction.md b/docs/construction.md index 5cb9871..bbc60b1 100644 --- a/docs/construction.md +++ b/docs/construction.md @@ -7,41 +7,38 @@ You can create them from: 3. sequences of ints or these things, or other sequences 4. explicitly, like you would create a `range` or `slice` -Essentially, the constructor has `value` and `stop` fields. If `stop` is -provided then `value` is assumed to be the `start`, otherwise it's assumed -you want to convert the `value` from something else. - ## Range from a string ```python -from arranges import Range +from arranges import Ranges + +# Create ranges from a string. Like a slice but without the square brackets. -# Create a range from a string. Like a slice but without the square brackets. -the_full_range = Range(":") # an endless sequence starting at 0 -the_empty_range = Range("") # start, stop and len() are all 0 -from_0_to_99 = Range("0:100") -skip_10_items = Range("10:") # boundless, goes to infinity -access_by_index = Range("0") # just the first item +the_full_range = Ranges(":") # an endless sequence starting at 0 +the_empty_range = Ranges("") # start, stop and len() are all 0 +from_0_to_99 = Ranges("0:100") +skip_10_items = Ranges("10:") # boundless, goes to infinity +access_by_index = Ranges("0") # just the first item # Decimal, hexadecimal, octal and binary are supported. Note that octal uses # Python's 0o prefix, not 0 like in C. -gbc_palette = Range("0xff68:0xff88") -skip_bmp_header = Range("0o66:end") # skip "54", "0x36" or "0b1100110" bytes +gbc_palette = Ranges("0xff68:0xff88") +skip_bmp_header = Ranges("0o66:end") # skip "54", "0x36" or "0b1100110" bytes # "end" and "inf" are the same. You can also use "start" instead of 0. -the_full_range_again = Range("start:inf") +the_full_range_again = Ranges("start:inf") # whitespace is ignored during construction -first_kilobyte = Range("start : 0x400") +first_kilobyte = Ranges("start : 0x400") # They are simplified when converted to str, which they can be compared with. assert first_kilobyte == ":1024" # Comparisons work in both directions -assert "000001:000002" == Range("1") +assert "000001:000002" == Ranges("1") # and the hash is the same as the string -w = Range("6 : 8") +w = Ranges("6 : 8") assert hash(w) == hash("6:8") # so you can use them as dict keys @@ -76,51 +73,42 @@ can pass it in as the value. If the `step` value is something other than None or 1 then it'll raise `ValueError`. ```python -from arranges import Range +from arranges import Ranges -from_slice = Range(slice(10, 20)) -from_range = Range(range(10, 20)) -from_other = Range(Range("10:20")) +from_slice = Ranges(slice(10, 20)) +from_range = Ranges(range(10, 20)) +from_other = Ranges(Ranges("10:20")) assert from_slice == from_range == from_other == "10:20" ``` ## Ranges from sequences -When creating a Range object from a sequence, it'll have to be in sequential -order with no gaps. Duplicates are absorbed. - ```python -from arranges import Range +from arranges import Ranges l = list(range(100)) t = tuple(range(100)) i = (i for i in range(100)) -assert Range(l) == Range(t) == Range(i) == ":100" -``` - -`Ranges` are much more forgiving: - -```python -from arranges import Ranges +assert Ranges(l) == Ranges(t) == Ranges(i) == ":100" jumble = Ranges([0, [2, 4], ["1:3"], 3, 4, range(10, 20)]) assert jumble == "5,10:20" ``` -## Explicitly creating a Range +## Explicitly creating Ranges You can create them in the same way as `range` or `slice` objects which have a slightly different syntax to slice notation. ```python -from arranges import Range, inf +from arranges import Ranges, inf -assert Range(10, inf) == "10:" +assert Ranges(10, inf) == "10:" -# Range("10") is not the same as Range(10) -assert Range(10) == ":10" -assert Range("10") == 10 == Range(10, 11) +# Ranges("10") is not the same as Ranges(10) +assert Ranges(10) == ":10" +assert Ranges("10") == 10 == Ranges(10, 11) ``` diff --git a/docs/iteration.md b/docs/iteration.md index 0051ad6..2801c33 100644 --- a/docs/iteration.md +++ b/docs/iteration.md @@ -1,7 +1,6 @@ # Iteration -Both the `Range` and `Ranges` objects are sequences of integers that you can -iterate over. +`Ranges` objects are sequences of integers that you can iterate over. ```python from arranges import Ranges @@ -24,9 +23,9 @@ import math import sys from arranges import Ranges, inf -assert len(Range("1,2,3,4,10:20")) == 14 +assert len(Ranges("1,2,3,4,10:20")) == 14 -full = Range(":") +full = Ranges(":") assert len(full) == sys.maxsize assert len(full) == inf @@ -46,11 +45,10 @@ assert type(len(full)) is int Empty ranges are, of course, Falsey. ```python -from arranges import Range, Ranges +from arranges import Ranges assert Ranges(":") assert Range(10) assert not Ranges("") -assert not Range("") ``` diff --git a/docs/models.md b/docs/models.md index 36fe2ea..2baadbd 100644 --- a/docs/models.md +++ b/docs/models.md @@ -1,5 +1,7 @@ # Use in Pydantic models +You'll need Pydantic >=2.3: + ```python from pydantic import BaseModel, Field @@ -8,8 +10,14 @@ class BinaryPatch(BaseModel): """ """ - regions: Ranges = Ranges(":") + regions: Ranges +model = BinaryPatch.model_validate_json(""" +{ + "regions": "0:10, 20:30, 15:, 0x0b" +} +""") +assert model.regions == ":10,15:" ``` diff --git a/docs/operators.md b/docs/operators.md index 4043f96..28aaa5b 100644 --- a/docs/operators.md +++ b/docs/operators.md @@ -3,6 +3,9 @@ They try to be set-like, supporting most of the operations that the `set` object does. +Actually, dunno how much of this I'm missing. Raise a ticket if there are +gaps. + | **Symbol** | **Name** | **Code** | |:----------:|:--------------------:|:--------------------:| | `A ⋂ B` | intersection | `A & B` | @@ -17,5 +20,5 @@ object does. | `A ∆ B` | symmetric difference | `(A | B) - (A & B)` | | `a ∈ A` | membership | `a in A` | | `|A|` | cardinality | `len(A)` | -| `Ø` | empty set | `Range("")` | -| `ℕ0` | natural numbers | `Range(":")` | +| `Ø` | empty set | `Ranges("")` | +| `ℕ0` | natural numbers | `Ranges(":")` | diff --git a/mkdocs.yml b/mkdocs.yml index d33731d..aa15439 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,8 +10,8 @@ theme: - navigation.sections nav: - 'index.md' - - 'models.md' - 'construction.md' - 'iteration.md' - 'operators.md' + - 'models.md' - 'pydoc.md'