diff --git a/docs/src/content/docs/commands/LPOP.md b/docs/src/content/docs/commands/LPOP.md index d43dd6df8..055fa5c76 100644 --- a/docs/src/content/docs/commands/LPOP.md +++ b/docs/src/content/docs/commands/LPOP.md @@ -1,119 +1,133 @@ --- title: LPOP -description: Documentation for the DiceDB command LPOP +description: The `LPOP` command in DiceDB removes and returns the first element of a list at a specified key. This command is ideal for implementing queue-like data structures that process elements in a First-In-First-Out (FIFO) order. --- -The `LPOP` command is used to remove and return the first element of a list stored at a specified key in DiceDB. This command is useful for implementing queue-like structures where elements are processed in a First-In-First-Out (FIFO) order. +The `LPOP` command in DiceDB removes and returns the first element of a list at a specified key. This command is ideal for implementing queue-like data structures that process elements in a First-In-First-Out (FIFO) order. ## Syntax -``` +```plaintext LPOP key ``` ## Parameters -- `key`: The key of the list from which the first element will be removed and returned. The key must be a valid string. +| Parameter | Description | Type | Required | +| ----------- | --------------------------------------------------------------------------------| ------- | -------- | +| `key` | The key of the list from which the first element will be removed and returned. | String | Yes | + + ## Return Value -- `String`: The value of the first element in the list, if the list exists and is not empty. -- `nil`: If the key does not exist or the list is empty. +| Condition | Return Value | +|------------------------------------------------|-------------------------------------------------------------------------------------------| +| Command is successful | `String` The value of the first element in the list, if the list exists and is not empty. | +| If the key does not exist or the list is empty | `nil` | +| Syntax or specified constraints are invalid | error | -## Behaviour -When the `LPOP` command is executed: -1. If the key exists and is associated with a list, the first element of the list is removed and returned. -2. If the key does not exist, the command returns `nil`. -3. If the key exists but is not associated with a list, an error is returned. -4. If the list is empty, the command returns `nil`. +## Behavior -## Error Handling +- When the `LPOP` command is executed, DiceDB checks if the key exists and is associated with a list. If so, the first element of the list is removed and returned. +- If the key does not exist or the list is empty, the command returns `nil`. +- If the key exists but is not associated with a list, a `WRONGTYPE` error is returned. +- If more than one argument is passed, an error is returned. -- `WRONGTYPE Operation against a key holding the wrong kind of value`: This error is raised if the key exists but is not associated with a list. For example, if the key is associated with a string, set, or hash, this error will be returned. +## Errors -## Example Usage +1. `Wrong type of key` -### Example 1: Basic Usage +When the `LPOP` command is executed for a key that exists but is not associated with a list, an error is returned. This error occurs if the key is associated with a type other than a list, such as a string or set. -```DiceDB -RPUSH mylist "one" "two" "three" -LPOP mylist +```bash +127.0.0.1:7379> LPOP mystring +(error) WRONGTYPE Operation against a key holding the wrong kind of value ``` +2. `Wrong number of arguments` -`Output:` +If the `LPOP` command is executed with more than one key or no key, the following error is returned: +```bash +127.0.0.1:7379> LPOP +(error) ERR wrong number of arguments for 'lpop' command ``` -"one" + +```bash +127.0.0.1:7379> LPOP mylist secondlist +(error) ERR wrong number of arguments for 'lpop' command ``` -`Explanation:` +## Example Usage -- The list `mylist` initially contains the elements \["one", "two", "three"\]. -- The `LPOP` command removes and returns the first element, which is "one". -- The list `mylist` now contains \["two", "three"\]. +### Basic Usage +Setting a list `mylist` with elements \["one", "two", "three"\]. -### Example 2: List is Empty +```bash +RPUSH mylist "one" "two" "three" +``` +Removing the first element from the list `mylist` -```DiceDB -RPUSH mylist "one" -LPOP mylist +```bash LPOP mylist +"one" ``` -`Output:` +The list `mylist` now contains \["two", "three"\]. -``` -"one" -(nil) +If the LPOP command is executed one more time: +```bash +LPOP mylist +"two" ``` -`Explanation:` +The list `mylist` now contains \["three"\]. -- The list `mylist` initially contains the element \["one"\]. -- The first `LPOP` command removes and returns "one". -- The second `LPOP` command returns `nil` because the list is now empty. -### Example 3: Key Does Not Exist -```DiceDB -LPOP nonexistinglist -``` +### Empty List or Non-Existent Key -`Output:` +Returns `(nil)` if the list is empty or the provided key is non-existent -``` +```bash +LPOP emptylist (nil) ``` -`Explanation:` -- The key `nonexistinglist` does not exist in the database. -- The `LPOP` command returns `nil`. -### Example 4: Key is Not a List -```DiceDB +### Key is Not a List + +Setting a key `mystring` with the value `hello`: + +```bash SET mystring "hello" -LPOP mystring +OK ``` -`Output:` +Executing `LPOP` command on any key that is not associated with a List type will result in an error: -``` +```bash +LPOP mystring (error) WRONGTYPE Operation against a key holding the wrong kind of value ``` -`Explanation:` +### Wrong Number of Arguments + +Passing more than one key will result in an error: -- The key `mystring` is associated with a string value "hello". -- The `LPOP` command returns an error because `mystring` is not a list. +```bash +LPOP mylist secondlist +(error) ERR wrong number of arguments for 'lpop' command +``` -## Best Practices +### Notes -- Ensure that the key you are using with `LPOP` is associated with a list to avoid errors. -- Use `EXISTS` command to check if a key exists before using `LPOP` to handle cases where the key might not exist. +- The key used with the `LPOP` command should be associated with a list to avoid any potential errors. +- Use the `EXISTS` command to check if a key exists before using `LPOP` to handle cases where the key might not exist. - Consider using `LLEN` to check the length of the list if you need to handle empty lists differently. ## Related Commands