Struct SectionMut

pub struct SectionMut<'a, 'event> { /* private fields */ }

A opaque type that represents a mutable reference to a section.

Implementations

impl<'event> SectionMut<'_, 'event>

Mutating methods.

pub fn push<'b>( &mut self, value_name: ValueName<'event>, value: Option<&'b BStr>, ) -> &mut Self

Adds an entry to the end of this section name value_name and value. If value is None, no equal sign will be written leaving just the key. This is useful for boolean values which are true if merely the key exists.

pub fn push_with_comment<'b, 'c>( &mut self, value_name: ValueName<'event>, value: Option<&'b BStr>, comment: impl Into<&'c BStr>, ) -> &mut Self

Adds an entry to the end of this section name value_name and value. If value is None, no equal sign will be written leaving just the key. This is useful for boolean values which are true if merely the key exists. comment has to be the text to put right after the value and behind a # character. Note that newlines are silently transformed into spaces.

pub fn pop(&mut self) -> Option<(ValueName<'_>, Cow<'event, BStr>)>

Removes all events until a key value pair is removed. This will also remove the whitespace preceding the key value pair, if any is found.

pub fn set( &mut self, value_name: ValueName<'event>, value: &BStr, ) -> Option<Cow<'event, BStr>>

Sets the last key value pair if it exists, or adds the new value. Returns the previous value if it replaced a value, or None if it adds the value.

pub fn remove(&mut self, value_name: &str) -> Option<Cow<'event, BStr>>

Removes the latest value by key and returns it, if it exists.

pub fn push_newline(&mut self) -> &mut Self

Adds a new line event. Note that you don’t need to call this unless you’ve disabled implicit newlines.

pub fn newline(&self) -> &BStr

Return the newline used when calling push_newline().

pub fn set_implicit_newline(&mut self, on: bool) -> &mut Self

Enables or disables automatically adding newline events after adding a value. This is enabled by default.

pub fn set_leading_whitespace( &mut self, whitespace: Option<Cow<'event, BStr>>, ) -> &mut Self

Sets the exact whitespace to use before each newly created key-value pair, with only whitespace characters being permissible.

The default is 2 tabs. Set to None to disable adding whitespace before a key value.

Panics

If non-whitespace characters are used. This makes the method only suitable for validated or known input.

pub fn leading_whitespace(&self) -> Option<&BStr>

Returns the whitespace this section will insert before the beginning of a key, if any.

pub fn separator_whitespace(&self) -> (Option<&BStr>, Option<&BStr>)

Returns the whitespace to be used before and after the = between the key and the value.

For example, k = v will have (Some(" "), Some(" ")), whereas k=\tv will have (None, Some("\t")).

Methods from Deref<Target = Section<'event>>

pub fn header(&self) -> &Header<'a>

Return our header.

pub fn id(&self) -> SectionId

Return the unique id of the section, for use with the *_by_id() family of methods in gix_config::File.

pub fn body(&self) -> &Body<'a>

Return our body, containing all value names and values.

pub fn to_bstring(&self) -> BString

Serialize this type into a BString for convenience.

Note that to_string() can also be used, but might not be lossless.

pub fn write_to(&self, out: &mut dyn Write) -> Result<()>

Stream ourselves to the given out, in order to reproduce this section mostly losslessly as it was parsed.

pub fn meta(&self) -> &Metadata

Return additional information about this sections origin.

Methods from Deref<Target = Body<'a>>

pub fn value(&self, value_name: impl AsRef<str>) -> Option<Cow<'_, BStr>>

Retrieves the last matching value in a section with the given value name, if present.

Note that we consider values without separator = non-existing, i.e. [core]\na would not exist. If that’s expected, Self::value_implicit() must be used instead.

pub fn value_implicit(&self, value_name: &str) -> Option<Option<Cow<'_, BStr>>>

Retrieves the last matching value in a section with the given value name, if present, and indicates an implicit value with Some(None), and a non-existing one as None

pub fn values(&self, value_name: &str) -> Vec<Cow<'_, BStr>>

Retrieves all values that have the provided value name. This may return an empty vec, which implies there were no values with the provided key.

pub fn value_names(&self) -> impl Iterator<Item = &ValueName<'event>>

Returns an iterator visiting all value names in order.

pub fn contains_value_name(&self, value_name: &str) -> bool

Returns true if the section contains the provided value name.

pub fn num_values(&self) -> usize

Returns the number of values in the section.

pub fn is_void(&self) -> bool

Returns if the section is empty. Note that this may count whitespace, see num_values() for another way to determine semantic emptiness.

Trait Implementations

impl<'a, 'event> Debug for SectionMut<'a, 'event>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'event> Deref for SectionMut<'_, 'event>

type Target = Section<'event>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a, 'event> Hash for SectionMut<'a, 'event>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, 'event> Ord for SectionMut<'a, 'event>

fn cmp(&self, other: &SectionMut<'a, 'event>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'a, 'event> PartialEq for SectionMut<'a, 'event>

fn eq(&self, other: &SectionMut<'a, 'event>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, 'event> PartialOrd for SectionMut<'a, 'event>

fn partial_cmp(&self, other: &SectionMut<'a, 'event>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, 'event> Eq for SectionMut<'a, 'event>

impl<'a, 'event> StructuralPartialEq for SectionMut<'a, 'event>