From 6d9ab0d15c0809555f60bfdfa6e1ab1d0b166853 Mon Sep 17 00:00:00 2001 From: konsumlamm Date: Fri, 22 Jan 2021 01:44:59 +0100 Subject: [PATCH 1/2] Add std/setutils to lib.rst Improve doc comments for setutils --- doc/lib.rst | 62 ++++++++++++++++++++++---------------------- lib/std/setutils.nim | 17 +++++++----- 2 files changed, 42 insertions(+), 37 deletions(-) diff --git a/doc/lib.rst b/doc/lib.rst index cbab64775dcaf..2d39108190e5d 100644 --- a/doc/lib.rst +++ b/doc/lib.rst @@ -9,7 +9,7 @@ Nim Standard Library Nim's library is divided into *pure libraries*, *impure libraries*, and *wrappers*. -Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary +Pure libraries do not depend on any external `*.dll` or `lib*.so` binary while impure libraries do. A wrapper is an impure library that is a very low-level interface to a C library. @@ -37,11 +37,11 @@ Automatic imports * `threads `_ Basic Nim thread support. **Note:** This is part of the system module. Do not - import it explicitly. Enabled with ``--threads:on``. + import it explicitly. Enabled with `--threads:on`. * `channels `_ Nim message passing support for threads. **Note:** This is part of the - system module. Do not import it explicitly. Enabled with ``--threads:on``. + system module. Do not import it explicitly. Enabled with `--threads:on`. Core @@ -86,9 +86,11 @@ Algorithms This module implements some common generic algorithms like sort or binary search. * `sequtils `_ - This module implements operations for the built-in seq type + This module implements operations for the built-in `seq` type which were inspired by functional programming languages. +* `std/setutils `_ + This module adds functionality for the built-in `set` type. Collections @@ -100,7 +102,7 @@ Collections * `deques `_ Implementation of a double-ended queue. - The underlying implementation uses a ``seq``. + The underlying implementation uses a `seq`. * `heapqueue `_ Implementation of a heap data structure that can be used as a priority queue. @@ -115,7 +117,7 @@ Collections * `options `_ The option type encapsulates an optional value. -* `packedsets `_ +* `std/packedsets `_ Efficient implementation of a set of ordinals as a sparse bit set. * `sets `_ @@ -131,12 +133,11 @@ Collections Nim hash table support. Contains tables, ordered tables, and count tables. - String handling --------------- * `cstrutils `_ - Utilities for ``cstring`` handling. + Utilities for `cstring` handling. * `std/editdistance `_ This module contains an algorithm to compute the edit distance between two @@ -144,7 +145,7 @@ String handling * `encodings `_ Converts between different character encodings. On UNIX, this uses - the ``iconv`` library, on Windows the Windows API. + the `iconv` library, on Windows the Windows API. * `parseutils `_ This module contains helpers for parsing tokens, numbers, identifiers, etc. @@ -162,17 +163,17 @@ String handling * `strformat `_ Macro based standard string interpolation/formatting. Inspired by - Python's ``f``-strings. + Python's `f`-strings. * `strmisc `_ This module contains uncommon string handling operations that do not fit with the commonly used operations in strutils. * `strscans `_ - This module contains a ``scanf`` macro for convenient parsing of mini languages. + This module contains a `scanf` macro for convenient parsing of mini languages. * `strtabs `_ - The ``strtabs`` module implements an efficient hash table that is a mapping + The `strtabs` module implements an efficient hash table that is a mapping from strings to strings. Supports a case-sensitive, case-insensitive and style-insensitive modes. @@ -199,7 +200,7 @@ Time handling The `monotimes` module implements monotonic timestamps. * `times `_ - The ``times`` module contains support for working with time. + The `times` module contains support for working with time. Generic Operating System Services @@ -221,7 +222,7 @@ Generic Operating System Services data structures. * `memfiles `_ - This module provides support for memory-mapped files (Posix's ``mmap``) + This module provides support for memory-mapped files (Posix's `mmap`) on the different operating systems. * `os `_ @@ -230,7 +231,7 @@ Generic Operating System Services commands, etc. * `osproc `_ - Module for process communication beyond ``os.execShellCmd``. + Module for process communication beyond `os.execShellCmd`. * `streams `_ This module provides a stream interface and two implementations thereof: @@ -281,18 +282,18 @@ Internet Protocols and Support * `asyncfile `_ This module implements asynchronous file reading and writing using - ``asyncdispatch``. + `asyncdispatch`. * `asyncftpclient `_ - This module implements an asynchronous FTP client using the ``asyncnet`` + This module implements an asynchronous FTP client using the `asyncnet` module. * `asynchttpserver `_ - This module implements an asynchronous HTTP server using the ``asyncnet`` + This module implements an asynchronous HTTP server using the `asyncnet` module. * `asyncnet `_ - This module implements asynchronous sockets based on the ``asyncdispatch`` + This module implements asynchronous sockets based on the `asyncdispatch` module. * `asyncstreams `_ @@ -316,7 +317,7 @@ Internet Protocols and Support * `net `_ This module implements a high-level sockets API. It replaces the - ``sockets`` module. + `sockets` module. * `selectors `_ This module implements a selector API with backends specific to each OS. @@ -350,23 +351,23 @@ Parsers scheme for lexers and parsers. This is used by the diverse parsing modules. * `parsecfg `_ - The ``parsecfg`` module implements a high-performance configuration file - parser. The configuration file's syntax is similar to the Windows ``.ini`` + The `parsecfg` module implements a high-performance configuration file + parser. The configuration file's syntax is similar to the Windows `.ini` format, but much more powerful, as it is not a line based parser. String literals, raw string literals, and triple quote string literals are supported as in the Nim programming language. * `parsecsv `_ - The ``parsecsv`` module implements a simple high-performance CSV parser. + The `parsecsv` module implements a simple high-performance CSV parser. * `parseopt `_ - The ``parseopt`` module implements a command line option parser. + The `parseopt` module implements a command line option parser. * `parsesql `_ - The ``parsesql`` module implements a simple high-performance SQL parser. + The `parsesql` module implements a simple high-performance SQL parser. * `parsexml `_ - The ``parsexml`` module implements a simple high performance XML/HTML parser. + The `parsexml` module implements a simple high performance XML/HTML parser. The only encoding that is supported is UTF-8. The parser has been designed to be somewhat error-correcting, so that even some "wild HTML" found on the web can be parsed with it. @@ -411,7 +412,6 @@ Generators that generates a string with its HTML representation. - Hashing ------- @@ -435,7 +435,6 @@ Hashing This module implements a sha1 encoder and decoder. - Miscellaneous ------------- @@ -453,7 +452,7 @@ Miscellaneous This module implements a simple logger. * `segfaults `_ - Turns access violations or segfaults into a ``NilAccessDefect`` exception. + Turns access violations or segfaults into a `NilAccessDefect` exception. * `sugar `_ This module implements nice syntactic sugar based on Nim's macro system. @@ -475,11 +474,11 @@ Modules for JS backend Declaration of the Document Object Model for the JS backend. * `jsconsole `_ - Wrapper for the ``console`` object. + Wrapper for the `console` object. * `jscore `_ The wrapper of core JavaScript functions. For most purposes, you should be using - the ``math``, ``json``, and ``times`` stdlib modules instead of this module. + the `math`, `json`, and `times` stdlib modules instead of this module. * `jsffi `_ Types and macros for easier interaction with JavaScript. @@ -536,6 +535,7 @@ UNIX specific * `posix_utils `_ Contains helpers for the POSIX standard or specialized for Linux and BSDs. + Regular expressions ------------------- diff --git a/lib/std/setutils.nim b/lib/std/setutils.nim index c6385180e6261..c79b13f63bdc5 100644 --- a/lib/std/setutils.nim +++ b/lib/std/setutils.nim @@ -7,10 +7,14 @@ # distribution, for details about the copyright. # -## This module adds functionality to the built-in `set` type. -## See also std/packedsets, std/sets +## This module adds functionality for the built-in `set` type. +## +## See also +## ======== +## * `std/packedsets `_ +## * `std/sets `_ -import typetraits +import std/typetraits #[ type SetElement* = char|byte|bool|int16|uint16|enum|uint8|int8 @@ -18,15 +22,16 @@ import typetraits ]# template toSet*(iter: untyped): untyped = - ## Return a built-in set from the elements of iterable `iter` - runnableExamples: + ## Returns a built-in set from the elements of the iterable `iter`. + runnableExamples: assert "helloWorld".toSet == {'W', 'd', 'e', 'h', 'l', 'o', 'r'} assert toSet([10u16, 20, 30]) == {10u16, 20, 30} assert [30u8, 100, 10].toSet == {10u8, 30, 100} assert toSet(@[1321i16, 321, 90]) == {90i16, 321, 1321} assert toSet([false]) == {false} assert toSet(0u8..10) == {0u8..10} + var result: set[elementType(iter)] for x in iter: - incl(result, x) + result.incl(x) result From 6d87de98f1a6abc555e4638c6cfcd05959369367 Mon Sep 17 00:00:00 2001 From: konsumlamm Date: Fri, 22 Jan 2021 12:53:41 +0100 Subject: [PATCH 2/2] Adhere to the RST spec Use no UFCS in toSet --- doc/lib.rst | 64 ++++++++++++++++++++++---------------------- lib/std/setutils.nim | 2 +- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/lib.rst b/doc/lib.rst index 2d39108190e5d..6895d8efd0fa7 100644 --- a/doc/lib.rst +++ b/doc/lib.rst @@ -9,7 +9,7 @@ Nim Standard Library Nim's library is divided into *pure libraries*, *impure libraries*, and *wrappers*. -Pure libraries do not depend on any external `*.dll` or `lib*.so` binary +Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary while impure libraries do. A wrapper is an impure library that is a very low-level interface to a C library. @@ -37,11 +37,11 @@ Automatic imports * `threads `_ Basic Nim thread support. **Note:** This is part of the system module. Do not - import it explicitly. Enabled with `--threads:on`. + import it explicitly. Enabled with ``--threads:on``. * `channels `_ Nim message passing support for threads. **Note:** This is part of the - system module. Do not import it explicitly. Enabled with `--threads:on`. + system module. Do not import it explicitly. Enabled with ``--threads:on``. Core @@ -86,11 +86,11 @@ Algorithms This module implements some common generic algorithms like sort or binary search. * `sequtils `_ - This module implements operations for the built-in `seq` type + This module implements operations for the built-in ``seq`` type which were inspired by functional programming languages. * `std/setutils `_ - This module adds functionality for the built-in `set` type. + This module adds functionality for the built-in ``set`` type. Collections @@ -102,7 +102,7 @@ Collections * `deques `_ Implementation of a double-ended queue. - The underlying implementation uses a `seq`. + The underlying implementation uses a ``seq``. * `heapqueue `_ Implementation of a heap data structure that can be used as a priority queue. @@ -137,7 +137,7 @@ String handling --------------- * `cstrutils `_ - Utilities for `cstring` handling. + Utilities for ``cstring`` handling. * `std/editdistance `_ This module contains an algorithm to compute the edit distance between two @@ -145,7 +145,7 @@ String handling * `encodings `_ Converts between different character encodings. On UNIX, this uses - the `iconv` library, on Windows the Windows API. + the ``iconv`` library, on Windows the Windows API. * `parseutils `_ This module contains helpers for parsing tokens, numbers, identifiers, etc. @@ -163,17 +163,17 @@ String handling * `strformat `_ Macro based standard string interpolation/formatting. Inspired by - Python's `f`-strings. + Python's ``f``-strings. * `strmisc `_ This module contains uncommon string handling operations that do not fit with the commonly used operations in strutils. * `strscans `_ - This module contains a `scanf` macro for convenient parsing of mini languages. + This module contains a ``scanf`` macro for convenient parsing of mini languages. * `strtabs `_ - The `strtabs` module implements an efficient hash table that is a mapping + The ``strtabs`` module implements an efficient hash table that is a mapping from strings to strings. Supports a case-sensitive, case-insensitive and style-insensitive modes. @@ -197,10 +197,10 @@ Time handling ------------- * `std/monotimes `_ - The `monotimes` module implements monotonic timestamps. + The ``monotimes`` module implements monotonic timestamps. * `times `_ - The `times` module contains support for working with time. + The ``times`` module contains support for working with time. Generic Operating System Services @@ -222,7 +222,7 @@ Generic Operating System Services data structures. * `memfiles `_ - This module provides support for memory-mapped files (Posix's `mmap`) + This module provides support for memory-mapped files (Posix's ``mmap``) on the different operating systems. * `os `_ @@ -231,12 +231,12 @@ Generic Operating System Services commands, etc. * `osproc `_ - Module for process communication beyond `os.execShellCmd`. + Module for process communication beyond ``os.execShellCmd``. * `streams `_ This module provides a stream interface and two implementations thereof: - the `FileStream` and the `StringStream` which implement the stream - interface for Nim file objects (`File`) and strings. Other modules + the ``FileStream`` and the ``StringStream`` which implement the stream + interface for Nim file objects (``File``) and strings. Other modules may provide other implementations for this standard stream interface. * `terminal `_ @@ -282,22 +282,22 @@ Internet Protocols and Support * `asyncfile `_ This module implements asynchronous file reading and writing using - `asyncdispatch`. + ``asyncdispatch``. * `asyncftpclient `_ - This module implements an asynchronous FTP client using the `asyncnet` + This module implements an asynchronous FTP client using the ``asyncnet`` module. * `asynchttpserver `_ - This module implements an asynchronous HTTP server using the `asyncnet` + This module implements an asynchronous HTTP server using the ``asyncnet`` module. * `asyncnet `_ - This module implements asynchronous sockets based on the `asyncdispatch` + This module implements asynchronous sockets based on the ``asyncdispatch`` module. * `asyncstreams `_ - This module provides `FutureStream` - a future that acts as a queue. + This module provides ``FutureStream`` - a future that acts as a queue. * `cgi `_ This module implements helpers for CGI applications. @@ -317,7 +317,7 @@ Internet Protocols and Support * `net `_ This module implements a high-level sockets API. It replaces the - `sockets` module. + ``sockets`` module. * `selectors `_ This module implements a selector API with backends specific to each OS. @@ -351,23 +351,23 @@ Parsers scheme for lexers and parsers. This is used by the diverse parsing modules. * `parsecfg `_ - The `parsecfg` module implements a high-performance configuration file - parser. The configuration file's syntax is similar to the Windows `.ini` + The ``parsecfg`` module implements a high-performance configuration file + parser. The configuration file's syntax is similar to the Windows ``.ini`` format, but much more powerful, as it is not a line based parser. String literals, raw string literals, and triple quote string literals are supported as in the Nim programming language. * `parsecsv `_ - The `parsecsv` module implements a simple high-performance CSV parser. + The ``parsecsv`` module implements a simple high-performance CSV parser. * `parseopt `_ - The `parseopt` module implements a command line option parser. + The ``parseopt`` module implements a command line option parser. * `parsesql `_ - The `parsesql` module implements a simple high-performance SQL parser. + The ``parsesql`` module implements a simple high-performance SQL parser. * `parsexml `_ - The `parsexml` module implements a simple high performance XML/HTML parser. + The ``parsexml`` module implements a simple high performance XML/HTML parser. The only encoding that is supported is UTF-8. The parser has been designed to be somewhat error-correcting, so that even some "wild HTML" found on the web can be parsed with it. @@ -452,7 +452,7 @@ Miscellaneous This module implements a simple logger. * `segfaults `_ - Turns access violations or segfaults into a `NilAccessDefect` exception. + Turns access violations or segfaults into a ``NilAccessDefect`` exception. * `sugar `_ This module implements nice syntactic sugar based on Nim's macro system. @@ -474,11 +474,11 @@ Modules for JS backend Declaration of the Document Object Model for the JS backend. * `jsconsole `_ - Wrapper for the `console` object. + Wrapper for the ``console`` object. * `jscore `_ The wrapper of core JavaScript functions. For most purposes, you should be using - the `math`, `json`, and `times` stdlib modules instead of this module. + the ``math``, ``json``, and ``times`` stdlib modules instead of this module. * `jsffi `_ Types and macros for easier interaction with JavaScript. diff --git a/lib/std/setutils.nim b/lib/std/setutils.nim index c79b13f63bdc5..215c7a76a7dab 100644 --- a/lib/std/setutils.nim +++ b/lib/std/setutils.nim @@ -33,5 +33,5 @@ template toSet*(iter: untyped): untyped = var result: set[elementType(iter)] for x in iter: - result.incl(x) + incl(result, x) result